Next: 11. Licence Up: 10. Alphabetical listing of Previous: 10.1 A warning about Contents Index
model elimination rule
, 
, 
} model elimination rules
Each user function is presented within it's own subsection with the documentation broken into multiple parts: the synopsis, the default arguments, and the sections from the function's docstring.
The synopsis presents a brief description of the function. It is taken as the first line of the docstring when browsing the help system.
This section lists all the arguments taken by the function and their default values. To invoke the function type the function name then in brackets type a comma separated list of arguments.
The first argument printed is always `self' but you can safely ignore it. `self' is part of the object oriented programming within Python and is automatically prefixed to the list of arguments you supply. Therefore you can't provide `self' as the first argument even if you do try.
All other sections are created from the sectioning of the user function docstring.
Function for copying alignment tensor data.
tensor_from: The identification string of the alignment tensor to copy the data from.
pipe_from: The name of the data pipe to copy the alignment tensor data from.
tensor_to: The identification string of the alignment tensor to copy the data to.
pipe_to: The name of the data pipe to copy the alignment tensor data to.
This function will copy the alignment tensor data to a new tensor or a new data pipe. The destination data pipe must not contain any alignment tensor data corresponding to the tensor_to label. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe. Both the tensor_from and tensor_to arguments must be supplied.
To copy the alignment tensor data corresponding to `Pf1' from the data pipe `old' to the current data pipe, type one of:
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Pf1', `old')
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Pf1', pipe_from=
[0]
[0]`old')
To copy the alignment tensor data corresponding to `Otting' from the current data pipe to the data pipe new, type one of:
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Otting', pipe_to=
[0]
[0]`new')
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Otting', pipe_to=
[0]
[0]`new')
To copy the alignment tensor data of `Otting' to that of `Otting new', type one of:
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Otting', tensor_to=
[0]
[0]`Otting new')
relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Pf1', tensor_to=
[0]
[0]`Otting new')
Function for deleting alignment tensor data.
tensor: The alignment tensor identification string.
This function will delete the specified alignment tensor data from the current data pipe.
Function for displaying the alignment tensor information.
tensor: The alignment tensor identification string.
Fix all alignment tensors so that they do not change during optimisation.
id: The alignment tensor identification string.
fixed: The flag specifying if the tensors should be fixed or variable.
If the ID string is left unset, then all alignment tensors will be fixed.
Function for initialising the alignment tensor.
tensor: The alignment tensor identification string.
params: The alignment tensor data.
scale: The alignment tensor eigenvalue scaling value.
angle_units: The units for the angle parameters.
param_types: A flag to select different parameter combinations.
errors: A flag which determines if the alignment tensor data or its errors are being input.
Using this function, the alignment tensor data can be set up. The params argument should be a tuple of floating point numbers (a list surrounded by round brakets). These correspond to the parameters of the tensor, which can be specified by the param_types argument, where the values correspond to
Other formats may be added later. The relationship between the Saupe order matrix S and the alignment tensor A is
The probability matrix P is related to the alignment tensor A by
where I is the identity matrix. For the alignment tensor to be supplied in Hertz, the bond vectors must all be of equal length.
To set a rhombic tensor to the run `CaM', type one of:
relax> align_tensor.
[0]
[0]
[0]init(
[0]
[0]`super media', (
[0]
[0]-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=
[0]
[0]1)
relax> align_tensor.
[0]
[0]
[0]init(
[0]
[0]tensor=
[0]
[0]`super media', params=
[0]
[0](
[0]
[0]-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=
[0]
[0]1)
Function for calculating the 5D angles between all alignment tensors.
basis_set: The basis set to operate with.
tensors: A list of the tensors to apply the calculation to. If None, all tensors are used.
This function will calculate the angles between all loaded alignment tensors for the current data pipe. The matrices are first converted to a 5D vector form and then then angles are calculated. The angles are dependent on the basis set. If the basis_set argument is set to the default of 0, the vectors {Sxx, Syy, Sxy, Sxz, Syz} are used. If the basis_set argument is set to 1, the vectors {Szz, Sxxyy, Sxy, Sxz, Syz} are used instead.
Specify that one tensor is a reduction of another.
full_tensor: The full alignment tensor.
red_tensor: The reduce alignment tensor.
Prior to optimisation of the N-state model and Frame Order theories using alignment tensors, which tensor is a reduction of which other tensor must be specified through this user function.
To state that the alignment tensor loaded as `chi3 C-dom' is a reduction of `chi3 N-dom', type:
relax> align_tensor.
[0]
[0]reduction(
[0]
[0]full_tensor=
[0]
[0]`chi3 N-dom', red_tensor=
[0]
[0]`chi3 C-dom')
Set the domain label for the alignment tensor.
tensor: The alignment tensor to assign the domain label to.
domain: The domain label.
Prior to optimisation of the N-state model or Frame Order theories, the domain to which each alignment tensor belongs must be specified.
To link the alignment tensor loaded as `chi3 C-dom' to the C-terminal domain `C', type:
relax> align_tensor.
[0]
[0]set_domain(
[0]
[0]tensor=
[0]
[0]`chi3 C-dom', domain=
[0]
[0]`C')
Function for calculating the singular values for all tensors and the condition number.
basis_set: The basis set to operate with.
tensors: A list of the tensors to apply the calculation to. If None, all tensors are used.
This function will, using SVD, calculate the singular values of all tensors loaded for the current data pipe. If the basis_set argument is set to the default of 0, the matrix on which SVD will be performed is composed of the unitary basis set {Sxx, Syy, Sxy, Sxz, Syz} layed out as:
| Sxx1 Syy1 Sxy1 Sxz1 Syz1 |
| Sxx2 Syy2 Sxy2 Sxz2 Syz2 |
| Sxx3 Syy3 Sxy3 Sxz3 Syz3 |
| . . . . . |
| . . . . . |
| . . . . . |
| SxxN SyyN SxyN SxzN SyzN |
If basis_set is set to 1, the geometric basis set consisting of the stretching and skewing parameters Szz and Sxx-yy respectively {Szz, Sxxyy, Sxy, Sxz, Syz} will be used instead. The matrix is:
| Szz1 Sxxyy1 Sxy1 Sxz1 Syz1 |
| Szz2 Sxxyy2 Sxy2 Sxz2 Syz2 |
| Szz3 Sxxyy3 Sxy3 Sxz3 Syz3 |
| . . . . . |
| . . . . . |
| . . . . . |
| SzzN SxxyyN SxyN SxzN SyzN |
The relationships between the geometric and unitary basis sets are:
Szz = - Sxx - Syy,
Sxxyy = Sxx - Syy,
The SVD values and condition number are dependendent upon the basis set chosen.
Calculate the angles defining the XH bond vector within the diffusion frame.
If the diffusion tensor is isotropic, then nothing will be done.
If the diffusion tensor is axially symmetric, then the angle 
will be calculated for each XH bond vector.
If the diffusion tensor is asymmetric, then the three angles will be calculated.
Specify a citation to be added the BMRB data file.
cite_id: The citation ID string.
authors: The list of authors. Each author element is a list of four elements (the first name, last name, first initial, and middle initials).
doi: The DOI number, e.g. "10.1000/182".
pubmed_id: The identification code assigned to the publication by PubMed.
full_citation: The full citation as given in a reference list.
title: The title of the publication.
status: The publication status.
journal_abbrev: The standard journal abbreviation.
journal_full: The full journal name.
volume: The volume number.
issue: The issue number.
page_first: The first page number.
page_last: The last page number.
year: The publication year.
The full_citation should be in a format similar to that used in a journal article by either cutting and pasting from another document or by typing. Please include author names, title, journal, page numbers, and year or equivalent information for the type of publication given.
The journal status can only be one of:
The citation type can only be one of:
The standard journal abbreviation is that defined by the Chemical Abstract Services for the journal where the data are or will be published. If the data in the deposition are related to a J. Biomol. NMR paper, the value must be `J. Biomol. NMR' to alert the BMRB annotators so that the deposition is properly processed. If the depositor truly does not know the journal, a value of `not known' or `na' is acceptable.
To add the citation "d'Auvergne E. J., Gooley P.
. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494.", type:
relax> bmrb.
[0]
[0]
[0]citation(
[0]
[0]authors=
[0]
[0][["Edward", "d'Auvergne", "E.", "J."], ["Paul", "Gooley", "P.", "R."]], doi=
[0]
[0]"10.1039/b702202f", pubmed_id=
[0]
[0]"17579774", full_citation=
[0]
[0]"d'Auvergne E. J., Gooley P. R. (
[0]
[0]2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(
[0]
[0]7), 483-494.", title=
[0]
[0]"Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm.", status=
[0]
[0]"published", type=
[0]
[0]"journal", journal_abbrev=
[0]
[0]"Mol. Biosyst.", journal_full=
[0]
[0]"Molecular Biosystems", volume=
[0]
[0]3, issue=
[0]
[0]7, page_first=
[0]
[0]483, page_last=
[0]
[0]498, year=
[0]
[0]2007)
Display the BMRB data in NMR-STAR format.
Read BMRB files in the NMR-STAR format.
file: The name of the BMRB STAR formatted file.
dir: The directory where the file is located.
version: For the reading to use the given NMR-STAR version.
sample_conditions: The sample conditions label in the NMR-STAR file to restrict loading to.
To search for the results file in the current working directory, set dir to None. Note that only one sample condition can be read per relax data pipe. Therefore if sample_conditions is not given and multiple conditions exist in the NMR-STAR file, a RelaxError will be raised.
Specify the scripts used in the analysis.
dir: The directory name.
analysis_type: The type of analysis performed.
model_selection: The model selection technique used, if relevant.
engine: The software engine used in the analysis.
model_elim: A model-free specific flag specifying if model elimination was performed.
universal_solution: A model-free specific flag specifying if the universal solution was sought after.
This user function allows scripts used in the analysis to be included in the BMRB deposition. The following addition information may need to be specified with the script.
The analysis_type must be set. Allowable values include all the data pipe types used in relax, ie:
The model_selection argument only needs to be set if the script selects between different mathematical models. This can be anything, but the following are recommended:
The engine is the software used in the calculation, optimisation, etc. This can be anything, but those recognised by relax (automatic program info, citations, etc. added) include:
or R
values.
The model_elim flag is model-free specific and should be set if the methods from "d'Auvergne, E. J. and Gooley, P.
. (2006). Model-free model elimination: A new step in the model-free dynamic analysis of NMR relaxation data. J. Biomol. NMR, 35(2), 117-135." were used. This should be set to True for the full_analysis.py script.
The universal_solution flag is model-free specific and should be set if the methods from "d'Auvergne E. J., Gooley P.
. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494." were used. This should be set to True for the full_analysis.py script.
For BMRB deposition, to specify that the full_analysis.py script was used, type one of:
relax> bmrb.
[0]
[0]script(
[0]
[0]`full_analysis.
[0]
[0]py', `model-free', `AIC', `relax', True, True)
relax> bmrb.
[0]
[0]script(
[0]
[0]file=
[0]
[0]`full_analysis.
[0]
[0]py', dir=
[0]
[0]None, analysis_type=
[0]
[0]`model-free', model_selection=
[0]
[0]`AIC', engine=
[0]
[0]`relax', model_elim=
[0]
[0]True, universal_solution=
[0]
[0]True)
Specify the software used in the analysis.
name: The name of the software program utilised.
version: The version of the software, if applicable.
url: The web address of the software.
vendor_name: The name of the company or person behind the program.
cite_ids: A list of the citation ID numbers.
tasks: A list of all the tasks performed by the software.
This user function allows the software used in the analysis to be specified in full detail.
For the tasks list, this should be a python list of strings (eg. [`spectral processing']). Although not restricted to these, the values suggested by the BMRB are:
For BMRB deposition, to say that Sparky was used in the analysis, type:
relax> cite_id =
[0]
[0]bmrb.
[0]
[0]
[0]citation(
[0]
[0]authors=
[0]
[0][[`Tom', `Goddard', `T.', `D.'], [`D', `Kneller', `D.', `G.']], title=
[0]
[0]""Goddard, T. D. and Kneller, D. G., SPARKY 3, University of California, San Francisco."
relax> bmrb.
[0]
[0]software(
[0]
[0]`Sparky', version=
[0]
[0]`3.110', url=
[0]
[0]"http://www.
[0]
[0]
[0]cgl.
[0]
[0]ucsf.
[0]
[0]
[0]edu/home/sparky/", vendor_name=
[0]
[0]"Goddard, T. D.", cite_ids=
[0]
[0][cite_id], tasks=
[0]
[0]["spectral analysis"])
Select the software used in the analysis.
name: The name of the software program utilised.
version: The version of the software, if applicable.
Rather than specifying all the information directly, this user function allows the software packaged used in the analysis to be selected by name. The programs currently supported are:
More can be added if all relevant information (program name, description, website, original citation, purpose, etc.) is emailed to relax-users@gna.org.
Note that relax is automatically added to the BMRB file.
For BMRB deposition, to say that both NMRPipe and Sparky were used prior to relax, type:
relax> bmrb.
[0]
[0]software_select(
[0]
[0]`NMRPipe')
relax> bmrb.
[0]
[0]software_select(
[0]
[0]`Sparky', version=
[0]
[0]`3.113')
Select the thiol state of the system.
state: The thiol state.
The thiol state can be any text, thought the BMRB suggests the following:
Alternatively the pure states `reduced' or `oxidised' could be specified.
For BMRB deposition, to say that the protein studied is in the oxidised state, tyype one of:
relax> bmrb.
[0]
[0]thiol_state(
[0]
[0]`oxidised')
relax> bmrb.
[0]
[0]thiol_state(
[0]
[0]state=
[0]
[0]`oxidised')
Write the results to a BMRB NMR-STAR formatted file.
.sconsign.dblite
Function for calculating the function value.
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
Function for selecting which relaxation data to use in the consistency tests.
frq: The spectrometer frequency in Hz.
This function will select the relaxation data to use in the consistency tests corresponding to the given frequencies.
relax> consistency_tests.
[0]
[0]set_frq(
[0]
[0]600.0 * 1e6)
relax> consistency_tests.
[0]
[0]set_frq(
[0]
[0]frq=
[0]
[0]600.0 * 1e6)
Function for creating the Dasha script.
algor: The minimisation algorithm.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
The script file created is called `dir/dasha_script'.
The two minimisation algorithms within Dasha are accessible through the algor argument which can be set to:
For Levenberg-Marquardt minimisation, the function `lmin' will be called, while for Newton -Raphson, the function `min' will be executed.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
binary: The name of the executable Dasha program file.
$ dasha < dasha_script | tee dasha_results
If you would like to use a different Dasha executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path in front of the binary file name.
Function for extracting data from the Dasha results file.
dir: The directory where the file `dasha_results' is found.
Deselect all spins.
This will deselect all spins, irregardless of their current state.
To deselect all spins, simply type:
relax> deselect.
[0]
[0]
[0]all(
[0]
[0])
Deselect the spins contained in a file.
file: The name of the file containing the list of spins to deselect.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
boolean: The boolean operator specifying how spins should be selected.
change_all: A flag specifying if all other spins should be changed.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the molecule name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin ID string can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
Empty lines and lines beginning with a hash are ignored.
The `change all' flag default is False meaning that all spins currently either selected or deselected will remain that way. Setting this to True will cause all spins not specified in the file to be selected.
To deselect all overlapped residues listed with residue numbers in the first column of the file `unresolved', type one of:
relax> deselect.
[0]
[0]read(
[0]
[0]`unresolved', res_num_col=
[0]
[0]1)
relax> deselect.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`unresolved', res_num_col=
[0]
[0]1)
To deselect the spins in the second column of the relaxation data file `r1.600' while selecting all other spins, for example type:
relax> deselect.
[0]
[0]read(
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
relax> deselect.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
The boolean operator can be used to change how spin systems are selected. The allowed values are: `OR', `NOR', `AND', `NAND', `XOR', `XNOR'. The following table details how the selections will occur for the different boolean operators.
(see table 10.1)
Reversal of the spin selection for the given spins.
spin_id: The spin ID string.
By supplying the spin ID string, a subset of spins can have their selection status reversed.
To deselect all currently selected spins and select those which are deselected type:
relax> deselect.
[0]
[0]reverse(
[0]
[0])
Deselect specific spins.
spin_id: The spin ID string.
change_all: A flag specifying if all other spins should be changed.
The `change all' flag default is False meaning that all spins currently either selected or deselected will remain that way. Setting this to True will cause all spins not specified by the spin ID string to be selected.
To deselect all glycines and alanines, type:
relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:GLY|:ALA')
To deselect residue 12 MET type:
relax> deselect.
[0]
[0]spin(
[0]
[0]`:12')
relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:12')
relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:12&:MET')
Function for copying diffusion tensor data from one data pipe to another.
pipe_from: The name of the data pipe to copy the diffusion tensor data from.
pipe_to: The name of the data pipe to copy the diffusion tensor data to.
This function will copy the diffusion tensor data between data pipes. The destination data pipe must not contain any diffusion tensor data. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe (hence giving one argument is essential).
To copy the diffusion tensor from the data pipe `m1' to the current data pipe, type:
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]`m1')
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1')
To copy the diffusion tensor from the current data pipe to the data pipe `m9', type:
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m9')
To copy the diffusion tensor from the data pipe `m1' to `m2', type:
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')
relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')
Function for deleting diffusion tensor data.
This function will delete all diffusion tensor data from the current data pipe.
Function for displaying the diffusion tensor information.
Function for initialising the diffusion tensor.
params: The diffusion tensor data.
time_scale: The correlation time scaling value.
d_scale: The diffusion tensor eigenvalue scaling value.
angle_units: The units for the angle parameters.
param_types: A flag to select different parameter combinations.
spheroid_type: A string which, if supplied together with spheroid parameters, will restrict the tensor to either being `oblate' or `prolate'.
fixed: A flag specifying whether the diffusion tensor is fixed or can be optimised.
When the molecule diffuses as a sphere, all three eigenvalues of the diffusion tensor are equal,
=
=
. In this case, the orientation of the XH bond vector within the diffusion frame is inconsequential to relaxation, hence, the spherical or Euler angles are undefined. Therefore solely a single geometric parameter, either
or
, can fully and sufficiently parameterise the diffusion tensor. The correlation function for the global rotational diffusion is
1 - tau / tm
C(tau) = - e ,
5
To select isotropic diffusion, the parameters argument should be a single floating point number. The number is the value of the isotropic global correlation time,
, in seconds. To specify the time in nanoseconds, set the `time_scale' argument to 1e-9. Alternative parameters can be used by changing the `param_types' flag to the following integers
where
= 6
.
When two of the three eigenvalues of the diffusion tensor are equal, the molecule diffuses as a spheroid. Four pieces of information are required to specify this tensor, the two geometric parameters,
and
, and the two orientational parameters, the polar angle 
and the azimuthal angle 
describing the orientation of the axis of symmetry. The correlation function of the global diffusion is
_1_
1 \ - tau / tau_i
C(tau) = - > ci . e ,
5 /__
i=-1
where
^2 - 1)^2,
^2 (1 -
^2),
^2 - 1)^2,
and
-1 = 6
- 2
,
0 = 6
-
,
1 = 6
+ 2
.
The direction cosine
is defined as the cosine of the angle
between the XH bond vector and the unique axis of the diffusion tensor.
To select axially symmetric anisotropic diffusion, the parameters argument should be a tuple of floating point numbers of length four. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, `param_types', are
,
,
,
} (Default),
,
,
,
},
,
,
,
},
,
,
,
},
,
,
,
},
where
= 1 / 6
,
= 1/3 (
+ 2
),
=
-
,
=
/
.
The spherical angles {
,
} orienting the unique axis of the diffusion tensor within the PDB frame are defined between
,
2
,
while the angle
which is the angle between this axis and the given XH bond vector is defined between
2
.
The `spheroid_type' argument should be `oblate', `prolate', or None. The argument will be ignored if the diffusion tensor is not axially symmetric. If `oblate' is given, then the constraint
0 is used while if `prolate' is given, then the constraint
0 is used. If nothing is supplied, then
will be allowed to have any values. To prevent minimisation of diffusion tensor parameters in a space with two minima, it is recommended to specify which tensor is to be minimised, thereby partitioning the two minima into the two subspaces along the boundry
= 0.
When all three eigenvalues of the diffusion tensor are different, the molecule diffuses as an ellipsoid. This diffusion is also known as fully anisotropic, asymmetric, or rhombic. The full tensor is specified by six pieces of information, the three geometric parameters
,
, and
representing the isotropic, anisotropic, and rhombic components of the tensor, and the three Euler angles
, 
, and 
orienting the tensor within the PDB frame. The correlation function is
_2_
1 \ - tau / tau_i
C(tau) = - > ci . e ,
5 /__
i=-2
where the weights on the exponentials are
^2
^2,
^2
^2,
^2
^2,
Let
= sqrt(1 + 3
),
then
^4 +
^4 +
^4) - 1,
((1 + 3
)(
^4 + 2
^2
^2) + (1 - 3
)(
^4 + 2
^2
^2) - 2(
^4 + 2
^2
^2)).
-2 = 6
- 2
.
,
-1 = 6
-
(1 + 3
),
0 = 6
-
(1 - 3
),
1 = 6
+ 2
,
1 = 6
+ 2
.
.
The three direction cosines
,
, and
are the coordinates of a unit vector parallel to the XH bond vector. Hence the unit vector is [
,
,
].
To select fully anisotropic diffusion, the parameters argument should be a tuple of length six. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, `param_types', are
,
,
,
,
,
} (Default),
,
,
,
,
,
},
,
,
,
,
,
},
where
= 1 / 6
,
= 1/3 (
+
+
),
=
- (
+
)/2,
= (
-
)/2
.
The angles
,
, and
are the Euler angles describing the diffusion tensor within the PDB frame. These angles are defined using the z-y-z axis rotation notation where
is the initial rotation angle around the z-axis,
is the rotation angle around the y-axis, and
is the final rotation around the z-axis again. The angles are defined between
2
,
,
2
.
Within the PDB frame, the XH bond vector is described using the spherical angles
and
where
is the polar angle and
is the azimuthal angle defined between
,
2
.
When param_types is set to 3, then the elements of the diffusion tensor matrix defined within the PDB frame can be supplied.
The `time_scale' argument should be a floating point number. The only parameter affected by this value is
.
The `d_scale' argument should also be a floating point number. Parameters affected by this value are
,
,
,
,
,
, and
. Significantly,
is not affected.
The `angle_units' argument should either be the string `deg' or `rad'. Parameters affected are
,
,
,
, and
.
To set an isotropic diffusion tensor with a correlation time of 10 ns, type:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]10e-9)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0]10e-9)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]10.0, 1e-9)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0]10.0, time_scale=
[0]
[0]1e-9, fixed=
[0]
[0]True)
To select axially symmetric diffusion with a
value of 8.5 ns,
of 1.1,
value of 20 degrees, and
value of 20 degrees, type:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]8.5e-9, 1.1, 20.0, 20.0), param_types=
[0]
[0]2)
To select a spheroid diffusion tensor with a
value of 1.698e7,
value of 1.417e7,
value of 67.174 degrees, and
value of -83.718 degrees, type one of:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e7, 1.417e7, 67.174, -83.718), param_types=
[0]
[0]3)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e7, 1.417e7, 67.174, -83.718), param_types=
[0]
[0]3)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 67.174, -83.718), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 67.174, -83.718), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8)
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8, angle_units=
[0]
[0]`rad')
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8, angle_units=
[0]
[0]`rad', fixed=
[0]
[0]True)
To select ellipsoidal diffusion, type:
relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=
[0]
[0]2)
file: The file name prefix. For example if file is set to `temp', then the OpenDX program temp.net will be loaded.
dir: The directory to change to for running OpenDX. If this is set to None, OpenDX will be run in the current directory.
_exe: The OpenDX executable file.
vp_exec: A flag specifying whether to execute the visual program automatically at start-up. The default of True causes the program to be executed.
Create a map of the given space in OpenDX format.
params: The parameters to be mapped. This argument should be an array of strings, the meanings of which are described below.
map_type: The type of map to create. For example the default, a 3D isosurface, the type is `Iso3D'. See below for more details.
spin_id: The spin identification numbe.
inc: The number of increments to map in each dimension. This value controls the resolution of the map.
lower: The lower bounds of the space. If you wish to change the lower bounds of the map then supply an array of length equal to the number of parameters in the model. A lower bound for each parameter must be supplied. If nothing is supplied then the defaults will be used.
upper: The upper bounds of the space. If you wish to change the upper bounds of the map then supply an array of length equal to the number of parameters in the model. A upper bound for each parameter must be supplied. If nothing is supplied then the defaults will be used.
axis_incs: The number of increments or ticks displaying parameter values along the axes of the OpenDX plot.
file_prefix: The file name. All the output files are prefixed with this name. The main file containing the data points will be called the value of `file'. The OpenDX program will be called `file.net' and the OpenDX import file will be called `file.general'.
dir: The directory to output files to. Set this to `None' if you do not want the files to be placed in subdirectory. If the directory does not exist, it will be created.
point: An array of parameter values where a point in the map, shown as a red sphere, will be placed. The length must be equal to the number of parameters.
point_file: The name of that the point output files will be prefixed with.
remap: A user supplied remapping function. This function will receive the parameter array and must return an array of equal length.
The map type can be changed to one of the following supported map types:
(see table 10.2)
The following commands will generate a map of the extended model-free space for model `m5' consisting of the parameters {
, 
,
}. Files will be output into the directory `dx' and will be prefixed by `map'. In this case, the system is a protein and residue number 6 will be mapped.
relax> dx.
[0]
[0]map(
[0]
[0][`s2', `s2f', `ts'], spin_id=
[0]
[0]`:6')
relax> dx.
[0]
[0]map(
[0]
[0][`s2', `s2f', `ts'], spin_id=
[0]
[0]`:6', file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')
relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`s2', `s2f', `ts'], spin_id=
[0]
[0]`:6', inc=
[0]
[0]20, file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')
relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`s2', `s2f', `ts'], spin_id=
[0]
[0]`:6', map_type=
[0]
[0]`Iso3D', inc=
[0]
[0]20, file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')
To map the model-free space `m4' for residue 2, spin N6 defined by the parameters {
,
, 
}, name the results `test', and to place the files in the current directory, use one of the following commands:
relax> dx.
[0]
[0]map(
[0]
[0][`s2', `te', `rex'], spin_id=
[0]
[0]`:2@N6', file_prefix=
[0]
[0]`test', dir=
[0]
[0]None)
relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`s2', `te', `rex'], spin_id=
[0]
[0]`:2@N6', inc=
[0]
[0]100, file_prefix=
[0]
[0]`test', dir=
[0]
[0]None)
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
WILL match both `S2' and `s2'.
`s2s'.
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.3)
(see table 10.4)
Elimination or rejection of models.
function: A user supplied function for model elimination.
args: A tuple of arguments for model elimination.
This is used for model validation to eliminate or reject models prior to model selection. Model validation is a part of mathematical modelling whereby models are either accepted or rejected.
Empirical rules are used for model rejection and are listed below. However these can be overridden by supplying a function in the prompt and scripting modes. The function should accept five arguments, a string defining a certain parameter, the value of the parameter, the minimisation instance (ie the residue index if the model is residue specific), and the function arguments. If the model is rejected, the function should return True, otherwise it should return False. The function will be executed multiple times, once for each parameter of the model.
The `args' keyword argument should be a tuple, a list enclosed in round brackets, and will be passed to the user supplied function or the inbuilt function. For a description of the arguments accepted by the inbuilt functions, see below.
Once a model is rejected, the select flag corresponding to that model will be set to False so that model selection, or any other function, will then skip the model.
model elimination rule
The local
, in some cases, may exceed the value expected for a global correlation time. Generally the
value will be stuck at the upper limit defined for the parameter. These models are eliminated using the rule:
c
The default value of c is 50 ns, although this can be overridden by supplying the value (in seconds) as the first element of the args tuple.
,
,
} model elimination rules
These parameters may experience the same problem as the local
in that the model fails and the parameter value is stuck at the upper limit. These parameters are constrained using the formula (
,
,
2
). These failed models are eliminated using the rule:
,
,
c .
The default value of c is 1.5. Because of round-off errors and the constraint algorithm, setting c to 2 will result in no models being eliminated as the minimised parameters will always be less than 2
. The value can be changed by supplying the value as the second element of the tuple.
The `args' argument must be a tuple of length 2, the elements of which must be numbers. For example, to eliminate models which have a local
value greater than 25 ns and models with internal correlation times greater than 1.5 times
, set `args' to (25 * 1e-9, 1.5).
Function for either fixing or allowing parameter values to change during optimisation.
element: Which element to fix.
fixed: A flag specifying if the parameters should be fixed or allowed to change.
The keyword argument `element' can be any of the following:
`diff' - the diffusion tensor parameters. This will allow all diffusion tensor parameters to be toggled.
`all_spins' - using this keyword, all parameters from all spins will be toggled.
`all' - all parameter will be toggled. This is equivalent to combining both `diff' and `all_spins'.
The flag `fixed', if set to True, will fix parameters during optimisation whereas a value of False will allow parameters to vary.
Create a PDB file representing the Frame Order cone models.
size: The size of the geometric object in Å.
inc: The number of increments used to create the geometric object.
file: The name of the PDB file to create.
dir: The directory where the file is to be located.
force: A flag which, if set to True, will overwrite the any pre-existing file.
This function creates a PDB file containing an artificial geometric structure representing the Frame Order cone models.
There are four different types of residue within the PDB. The pivot point is represented as as a single carbon atom of the residue `PIV'. The cone consists of numerous H atoms of the residue `CON'. The cone axis vector is presented as the residue `AXE' with one carbon atom positioned at the pivot and the other 
Åaway on the cone axis (set by the size argument). Finally, if Monte Carlo have been performed, there will be multiple `MCC' residues representing the cone for each simulation, and multiple `MCA' residues representing the multiple cone axes.
To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined by the cone axis. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.
Match the domains to PDB files.
domain: The domain to associate the PDB file to.
pdb: The PDB file to associate the domain to.
To display the frame order cone models within Pymol, the two domains need to be associated with PDB files. Then the reference domain will be fixed in the PDB frame, and the moving domain will be rotated to its average position.
To set the `N' domain to the PDB file `bax_N_1J7O_1
.pdb', type one of:
relax> frame_order.
[0]
[0]
[0]domain_to_pdb(
[0]
[0]`N', `bax_N_1J7O_1st.
[0]
[0]pdb')
relax> frame_order.
[0]
[0]
[0]domain_to_pdb(
[0]
[0]domain=
[0]
[0]`N', pdb=
[0]
[0]`bax_N_1J7O_1st.
[0]
[0]pdb')
Set the pivot point for the two body motion in the structural coordinate system.
pivot: The pivot point for the motion (e.g. the position between the 2 domains in PDB coordinates).
To set the pivot point, type one of:
relax> frame_order.
[0]
[0]pivot(
[0]
[0][12.067, 14.313, -3.2675])
relax> frame_order.
[0]
[0]pivot(
[0]
[0]pivot=
[0]
[0][12.067, 14.313, -3.2675])
Set the reference domain for the `2-domain' Frame Order theories.
ref: The domain which will act as the frame of reference. This is only valid for the `2-domain' Frame Order theories.
Prior to optimisation of the `2-domain' Frame Order theories, which of the two domains will act as the frame of reference must be specified. This is important for the attachment of cones to domains, etc.
To set up the isotropic cone frame order model with `centre' domain being the frame of reference, type:
relax> frame_order.
[0]
[0]ref_domain(
[0]
[0]ref=
[0]
[0]`centre')
Select and set up the Frame Order model.
model: The name of the preset Frame Order model.
Prior to optimisation, the Frame Order model should be selected. These models consist of three parameter categories:
and y-axes are defined as the
and y-axes of the eigenframe.
rank order parameter.
The list of available models are:
Euler angle ave_pos_alpha is dropped from the model. The symmetry also collapses the eigenframe to a single z-axis defined by the parameters axis_theta and axis_phi.
To select the isotropic cone model, type:
relax> frame_order.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`iso cone')
Set the spectrometer frequency of the experiment.
id: The experiment identification string.
frq: The spectrometer frequency in Hertz.
This user function allows the spectrometer frequency of a given experiment to be set.
Visualise the file within Grace.
file: The name of the file.
dir: The directory name.
grace_exe: The Grace executable file.
This can be used to view the specified Grace `*.agr' file by opening it with the Grace program.
To view the file `s2.agr' in the directory `grace', type:
relax> grace.
[0]
[0]view(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]view(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]
[0]agr', dir=
[0]
[0]`grace')
x_data_type: The data type for the X-axis (no regular expression is allowed).
_data_type: The data type for the Y-axis (no regular expression is allowed).
spin_id: The spin identification string.
plot_data: The data to use for the plot.
norm: Flag for the normalisation of series type data.
file: The name of the file.
dir: The directory name.
force: A flag which, if set to True, will cause the file to be overwritten.
This is designed to be as flexible as possible so that any combination of data can be plotted. The output is in the format of a Grace plot (also known as ACE/gr, Xmgr, and xmgrace) which only supports two dimensional plots. Three types of keyword arguments can be used to create various types of plot. These include the X-axis and Y-axis data types, the spin identification string, and an argument for selecting what to plot.
The X-axis and Y-axis data type arguments should be plain strings, regular expression is not allowed. If the X-axis data type argument is not given, the plot will default to having the spin sequence along the x-axis. The two axes of the Grace plot can be absolutely any of the data types listed in the tables below. The only limitation, currently anyway, is that the data must belong to the same data pipe.
The spin identification string can be used to limit which spins are used in the plot. The default is that all spins will be used, however, these arguments can be used to select a subset of all spins, or a single spin for plots of Monte Carlo simulations, etc.
The property which is actually plotted can be controlled by the `plot_data' argument. It can be one of the following:
Normalisation is only allowed for series type data, for example the R
exponential curves, and will be ignored for all other data types. If the norm flag is set to True then the y-value of the first point of the series will be set to 1. This normalisation is useful for highlighting errors in the data sets.
To write the NOE values for all spins to the Grace file `noe.agr', type one of:
relax> grace.
[0]
[0]write(
[0]
[0]`spin', `noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`spin', y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr', force=
[0]
[0]True)
To create a Grace file of `s2' vs. `te' for all spins, type one of:
relax> grace.
[0]
[0]write(
[0]
[0]`s2', `te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`s2', y_data_type=
[0]
[0]`te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`s2', y_data_type=
[0]
[0]`te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr', force=
[0]
[0]True)
To create a Grace file of the Monte Carlo simulation values of `rex' vs. `te' for residue 123, type one of:
relax> grace.
[0]
[0]write(
[0]
[0]`rex', `te', spin_id=
[0]
[0]`:123', plot_data=
[0]
[0]`sims', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`rex', y_data_type=
[0]
[0]`te', spin_id=
[0]
[0]`:123', plot_data=
[0]
[0]`sims', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')
By plotting the peak intensities, the integrity of exponential relaxation curves can be checked and anomalies searched for prior to model-free analysis or reduced spectral density mapping. For example the normalised average peak intensities can be plotted verses the relaxation time periods for the relaxation curves of all residues of a protein. The normalisation, whereby the initial peak intensity of each residue I(0) is set to 1, emphasises any problems. To produce this Grace file, type:
relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`relax_times', y_data_type=
[0]
[0]`ave_int', file=
[0]
[0]`intensities_norm.
[0]
[0]
[0]agr', force=
[0]
[0]True, norm=
[0]
[0]True)
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
WILL match both `S2' and `s2'.
`s2s'.
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.5)
(see table 10.6)
(see table 10.7)
(see table 10.8)
(see table 10.9)
The grid search function.
lower: An array of the lower bound parameter values for the grid search. The length of the array should be equal to the number of parameters in the model.
upper: An array of the upper bound parameter values for the grid search. The length of the array should be equal to the number of parameters in the model.
inc: The number of increments to search over. If a single integer is given then the number of increments will be equal in all dimensions. Different numbers of increments in each direction can be set if `inc' is set to an array of integers of length equal to the number of parameters.
constraints: A boolean flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
Turn the function introductions off.
Turn the function introductions on.
Function for selecting which relaxation data to use in the 
mapping.
frq: The spectrometer frequency in Hz.
This function will select the relaxation data to use in the reduced spectral density mapping corresponding to the given frequency.
relax> jw_mapping.
[0]
[0]set_frq(
[0]
[0]600.0 * 1e6)
relax> jw_mapping.
[0]
[0]set_frq(
[0]
[0]frq=
[0]
[0]600.0 * 1e6)
The arguments, which should all be strings, specify the minimiser as well as its options. A minimum of one argument is required. As this calls the minfx function `generic_minimise' the full list of allowed arguments is shown below in the reproduced `generic_minimise' docstring. Ignore all sections except those labelled as minimisation algorithms and minimisation options. Also do not select the Method of Multipliers constraint algorithm as this is used in combination with the given minimisation algorithm if the keyword argument `constraints' is set to 1. The grid search algorithm should also not be selected as this is accessed using the `grid' function instead. The first argument passed will be set to the minimisation algorithm while all other arguments will be set to the minimisation options.
Keyword arguments differ from normal arguments having the form `keyword = value'. All arguments must precede keyword arguments in python. For more information see the examples section below or the python tutorial.
func_tol: The function tolerance. This is used to terminate minimisation once the function value between iterations is less than the tolerance. The default value is 1e-25.
grad_tol: The gradient tolerance. Minimisation is terminated if the current gradient value is less than the tolerance. The default value is None.
max_iterations: The maximum number of iterations. The default value is 1e7.
constraints: A boolean flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).
scaling: The diagonal scaling boolean flag. The default that scaling is on (scaling=True).
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
Diagonal scaling is the transformation of parameter values such that each value has a similar order of magnitude. Certain minimisation techniques, for example the trust region methods, perform extremely poorly with badly scaled problems. In addition, methods which are insensitive to scaling such as Newton minimisation may still benefit due to the minimisation of round off errors.
In Model-free analysis for example, if
= 0.5,
= 200 ps, and
= 15 1/s at 600 MHz, the unscaled parameter vector would be [0.5, 2.0e-10, 1.055e-18].
is divided by (2 *
* 600,000,000)**2 to make it field strength independent. The scaling vector for this model may be something like [1.0, 1e-9, 1/(2 *
* 6e8)**2]. By dividing the unscaled parameter vector by the scaling vector the scaled parameter vector is [0.5, 0.2, 15.0]. To revert to the original unscaled parameter vector, the scaled parameter vector and scaling vector are multiplied.
To apply Newton minimisation together with the GMW81 Hessian modification algorithm, the More and Thuente line search algorithm, a function tolerance of 1e-25, no gradient tolerance, a maximum of 10,000,000 iterations, constraints turned on to limit parameter values, and have normal printout, type any combination of:
relax> minimise(
[0]
[0]`newton')
relax> minimise(
[0]
[0]`Newton')
relax> minimise(
[0]
[0]`newton', `gmw')
relax> minimise(
[0]
[0]`newton', `mt')
relax> minimise(
[0]
[0]`newton', `gmw', `mt')
relax> minimise(
[0]
[0]`newton', `mt', `gmw')
relax> minimise(
[0]
[0]`newton', func_tol=
[0]
[0]1e-25)
relax> minimise(
[0]
[0]`newton', func_tol=
[0]
[0]1e-25, grad_tol=
[0]
[0]None)
relax> minimise(
[0]
[0]`newton', max_iter=
[0]
[0]1e7)
relax> minimise(
[0]
[0]`newton', constraints=
[0]
[0]True, max_iter=
[0]
[0]1e7)
relax> minimise(
[0]
[0]`newton', verbosity=
[0]
[0]1)
To use constrained Simplex minimisation with a maximum of 5000 iterations, type:
relax> minimise(
[0]
[0]`simplex', constraints=
[0]
[0]True, max_iter=
[0]
[0]5000)
All the text which follows is a reproduction of the docstring of the generic_minimise function from the minfx python package. Only take note of the minimisation algorithms and minimisation options sections, the other sections are not relevant for this function. The Grid search and Method of Multipliers algorithms CANNOT be selected as minimisation algorithms for this function.
The section entitled Keyword Arguments is also completely inaccessible therefore please ignore that text.
Generic minimisation function.
This is a generic function which can be used to access all minimisers using the same set of function arguments. These are the function tolerance value for convergence tests, the maximum number of iterations, a flag specifying which data structures should be returned, and a flag specifying the amount of detail to print to screen.
func: The function which returns the value.
dfunc: The function which returns the gradient.
d2func: The function which returns the Hessian.
args: The tuple of arguments to supply to the functions func, dfunc, and d2func.
x0: The vector of initial parameter value estimates (as an array).
min_algor: A string specifying which minimisation technique to use.
min_options: A tuple to pass to the minimisation function as the min_options keyword.
func_tol: The function tolerance value. Once the function value between iterations decreases below this value, minimisation is terminated.
grad_tol: The gradient tolerance value.
maxiter: The maximum number of iterations.
A: Linear constraint matrix m*n (A.x
).
: Linear constraint scalar vector (A.x
).
: Lower bound constraint vector (
).
: Upper bound constraint vector (
).
c: User supplied constraint function.
dc: User supplied constraint gradient function.
d2c: User supplied constraint Hessian function.
full_output: A flag specifying which data structures should be returned.
print_flag: A flag specifying how much information should be printed to standard output during minimisation. 0 means no output, 1 means minimal output, and values above 1 increase the amount of output printed.
The following values of the `full_output' flag will return, in tuple form, the following data
, f_count, g_count, h_count, warning)',
where the data names correspond to
A minimisation function is selected if the minimisation algorithm argument, which should be a string, matches a certain pattern. Because the python regular expression `match' statement is used, various strings can be supplied to select the same minimisation algorithm. Below is a list of the minimisation algorithms available together with the corresponding patterns.
This is a short description of python regular expression, for more information, see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
To select a minimisation algorithm, set the argument to a string which matches the given pattern.
Unconstrained line search methods:
(see table 10.10)
Unconstrained trust-region methods:
(see table 10.11)
Unconstrained conjugate gradient methods:
(see table 10.12)
Miscellaneous unconstrained methods:
(see table 10.13)
Constrained methods:
(see table 10.14)
(see table 10.15)
The minimisation options can be given in any order.
Line search algorithms. These are used in the line search methods and the conjugate gradient methods. The default is the Backtracking line search.
(see table 10.16)
Hessian modifications. These are used in the Newton, Dogleg, and Exact trust region algorithms.
(see table 10.17)
Hessian type, these are used in a few of the trust region methods including the Dogleg and Exact trust region algorithms. In these cases, when the Hessian type is set to Newton, a Hessian modification can also be supplied as above. The default Hessian type is Newton, and the default Hessian modification when Newton is selected is the GMW algorithm.
(see table 10.18)
For Newton minimisation, the default line search algorithm is the More and Thuente line search, while the default Hessian modification is the GMW algorithm.
Function to create a model-free model.
model: The name of the model-free model.
equation: The model-free equation.
params: The array of parameter names of the model.
spin_id: The spin identification string.
`mf_orig' selects the original model-free equations with parameters {
,
}. `mf_ext' selects the extended model-free equations with parameters {
,
,
,
}. `mf_ext2' selects the extended model-free equations with parameters {
,
, 
,
}.
The following parameters are accepted for the original model-free equation:
The following parameters are accepted for the extended model-free equation:
=
*
.
The following parameters are accepted for the extended 2 model-free equation:
The following parameters are accepted for all equations:
.
If `spin_id' is supplied then the model will only be created for the corresponding spins. Otherwise the model will be created for all spins.
The following commands will create the model-free model `m1' which is based on the original model-free equation and contains the single parameter `s2'.
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]`m1', `mf_orig', [`s2'])
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]model=
[0]
[0]`m1', params=
[0]
[0][`s2'], equation=
[0]
[0]`mf_orig')
The following commands will create the model-free model `large_model' which is based on the extended model-free equation and contains the seven parameters `s2f', `tf', `s2', `ts', `rex', `csa', `r'.
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]`large_model', `mf_ext', [`s2f', `tf', `s2', `ts', `rex', `csa', `r'])
relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]model=
[0]
[0]`large_model', params=
[0]
[0][`s2f', `tf', `s2', `ts', `rex', `csa', `r'], equation=
[0]
[0]`mf_ext')
Function for deleting all model-free data from the current data pipe.
To delete all model-free data, type:
relax> model_free.
[0]
[0]
[0]delete(
[0]
[0])
Function for removing the local
parameter from a model.
spin_id: The spin identification string.
This function will remove the local
parameter from the model-free parameter set. If there is no local
parameter within the set nothing will happen.
If no spin identification string is given, then the function will apply to all spins.
The following command will remove the parameter `tm':
relax> model_free.
[0]
[0]remove_tm(
[0]
[0])
Function for the selection of a preset model-free model.
model: The name of the preset model.
The standard preset model-free models are
,
},
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
The preset model-free models with optimisation of the CSA value are
},
,
},
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
}.
The preset model-free models with optimisation of the bond length are
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
,
,
,
,
},
,
,
,
,
,
},
, CSA,
}.
The preset model-free models with both optimisation of the bond length and CSA are
, CSA},
, CSA,
},
, CSA,
,
},
, CSA,
,
},
, CSA,
,
,
},
, CSA,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
,
},
, CSA,
}.
Warning: The models in the thirties range fail when using standard R
, R
, and NOE relaxation data. This is due to the extreme flexibly of these models where a change in the parameter `r' is compensated by a corresponding change in the parameter `csa' and vice versa.
Additional preset model-free models, which are simply extensions of the above models with the addition of a local
parameter are:
,
},
,
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
,
,
,
,
},
,
,
,
,
,
},
,
}.
The preset model-free models with optimisation of the CSA value are
, CSA},
, CSA,
},
, CSA,
,
},
, CSA,
,
},
, CSA,
,
,
},
, CSA,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
},
, CSA,
,
,
,
,
},
, CSA,
}.
The preset model-free models with optimisation of the bond length are
,
},
,
,
},
,
,
,
},
,
,
,
},
,
,
,
,
},
,
,
,
,
},
,
,
,
,
,
},
,
,
,
,
,
},
,
,
,
,
,
,
},
,
, CSA,
}.
The preset model-free models with both optimisation of the bond length and CSA are
,
, CSA},
,
, CSA,
},
,
, CSA,
,
},
,
, CSA,
,
},
,
, CSA,
,
,
},
,
, CSA,
,
,
},
,
, CSA,
,
,
,
},
,
, CSA,
,
,
,
},
,
, CSA,
,
,
,
,
},
,
, CSA,
}.
If `spin_id' is supplied then the model will only be selected for the corresponding spins. Otherwise the model will be selected for all spins.
To pick model `m1' for all selected spins, type:
relax> model_free.
[0]
[0]select_model(
[0]
[0]`m1')
relax> model_free.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`m1')
Function for model selection.
method: The model selection technique (see below).
modsel_pipe: The name of the new data pipe which will be created by this user function by the copying of the selected data pipe.
pipes: An array containing the names of all data pipes to include in model selection.
The following model selection methods are supported:
For the methods `Bootstrap', `Expect', and `Overall', the function `monte_carlo' should have previously been executed with the type argument set to the appropriate value to modify its behaviour.
If the pipes argument is not supplied then all data pipes will be used for model selection.
For model-free analysis, if the preset models 1 to 5 are minimised and loaded into the program, the following commands will carry out AIC model selection and to place the selected results into the `mixed' data pipe, type one of:
relax> model_selection(
[0]
[0]`AIC', `mixed')
relax> model_selection(
[0]
[0]method=
[0]
[0]`AIC', modsel_pipe=
[0]
[0]`mixed')
relax> model_selection(
[0]
[0]`AIC', `mixed', [`m1', `m2', `m3', `m4', `m5'])
relax> model_selection(
[0]
[0]method=
[0]
[0]`AIC', modsel_pipe=
[0]
[0]`mixed', pipes=
[0]
[0][`m1', `m2', `m3', `m4', `m5'])
Copy all data associated with a molecule.
pipe_from: The data pipe containing the molecule from which the data will be copied. This defaults to the current data pipe.
mol_from: The name of the molecule from which to copy data from.
pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.
mol_to: The name of the new molecule. If left blank, the new molecule will have the same name as the old.
This will copy all the data associated with a molecule to a second molecule. This includes all residue and spin system information. The new molecule name must be unique in the destination data pipe.
To copy the molecule data from the molecule `GST' to the new molecule `wt-GST', type:
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]`#GST', `#wt-GST')
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]mol_from=
[0]
[0]`#GST', mol_to=
[0]
[0]`#wt-GST')
To copy the molecule data of the molecule `Ap4Aase' from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]mol_from=
[0]
[0]`#ApAase', pipe_to=
[0]
[0]`m2')
relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', mol_from=
[0]
[0]`#ApAase', pipe_to=
[0]
[0]`m2', mol_to=
[0]
[0]`#ApAase')
mol_name: The name of the new molecule.
mol_type: The type of molecule.
This adds a new molecule data container to the relax data storage object. The same molecule name cannot be used more than once. The molecule type need not be specified. However, if given, it should be one of `protein', `DNA', `RNA', `organic molecule', `inorganic molecule', or `inorganic molecule'.
To create the molecules `Ap4Aase', `ATP', and `MgF4', type:
relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`Ap4Aase')
relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`ATP')
relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`MgF4')
Deleting molecules from the relax data store.
mol_id: The molecule ID string.
This can be used to delete a single or sets of molecules from the relax data store. The molecule will be deleted from the current data pipe.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Display the molecule information.
mol_id: The molecule ID string.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
mol_id: The molecule ID string corresponding to one or more molecules.
force: A flag which if True will cause the molecule to be renamed.
This simply allows molecules to be named (or renamed).
To rename the molecule `Ap4Aase' to `Inhib Ap4Aase', type one of:
relax> molecule.
[0]
[0]name(
[0]
[0]`#Ap4Aase', `Inhib Ap4Aase', True)
relax> molecule.
[0]
[0]name(
[0]
[0]mol_id=
[0]
[0]`#Ap4Aase', name=
[0]
[0]`Inhib Ap4Aase', force=
[0]
[0]True)
This assumes the molecule `Ap4Aase' already exists.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
mol_id: The molecule ID string corresponding to one or more molecules.
force: A flag which if True will cause the molecule to type to be overwritten.
This allows the type of the molecule to be specified. It can be one of:
To set the molecule `Ap4Aase' to the `protein' type, type one of:
relax> molecule.
[0]
[0]type(
[0]
[0]`#Ap4Aase', `protein', True)
relax> molecule.
[0]
[0]type(
[0]
[0]mol_id=
[0]
[0]`#Ap4Aase', type=
[0]
[0]`protein', force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Clear the Molmol command history.
This will clear the Molmol history from memory.
Execute a user supplied Molmol command.
command: The Molmol command to execute.
This allows Molmol commands to be passed to the program. This can be useful for automation or scripting.
To reinitialise the Molmol instance, type:
relax> molmol.
[0]
[0]
[0]command(
[0]
[0]"InitAll yes")
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
This allows spin specific values to be mapped to a structure through Molmol macros. Currently only the `classic' style, which is described below, is available.
To map the order parameter values,
, onto the structure using the classic style, type:
relax> molmol.
[0]
[0]macro_apply(
[0]
[0]`s2')
relax> molmol.
[0]
[0]macro_apply(
[0]
[0]data_type=
[0]
[0]`s2')
relax> molmol.
[0]
[0]macro_apply(
[0]
[0]data_type=
[0]
[0]`s2', style=
[0]
[0]"classic")
The values are coloured based on a linear colour gradient which is specified through the starting and ending colours. These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, `white' and [1.0, 1.0, 1.0] both select the same colour. Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the name. To explicitly select these lists, set the colour list to either `molmol' or `x11'.
Creator: Edward d'Auvergne
Argument string: "classic"
Description: The classic style draws the backbone of a protein in a cylindrical bond style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines.
Supported data types:
(see table 10.19)
The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.
(see table 10.20)
The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.
(see table 10.21)
Open and execute the Molmol macro file.
file: The name of the Molmol macro file.
dir: The directory name.
This user function is for opening and running a Molmol macro located within a text file.
To execute the macro file `s2.mac' located in the directory `molmol', type:
relax> molmol.
[0]
[0]macro_run(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]mac')
relax> molmol.
[0]
[0]macro_run(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]mac', dir=
[0]
[0]`molmol')
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
file: The name of the file.
dir: The directory name.
force: A flag which, if set to True, will cause the file to be overwritten.
This allows residues specific values to be mapped to a structure through the creation of a Molmol `*.mac' macro which can be executed in Molmol by clicking on `File, Macro, Execute User...'. Currently only the `classic' style, which is described below, is available.
To create a Molmol macro mapping the order parameter values,
, onto the structure using the classic style, type:
relax> molmol.
[0]
[0]macro_write(
[0]
[0]`s2')
relax> molmol.
[0]
[0]macro_write(
[0]
[0]data_type=
[0]
[0]`s2')
relax> molmol.
[0]
[0]macro_write(
[0]
[0]data_type=
[0]
[0]`s2', style=
[0]
[0]"classic", file=
[0]
[0]`s2.
[0]
[0]mac', dir=
[0]
[0]`molmol')
The values are coloured based on a linear colour gradient which is specified through the starting and ending colours. These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, `white' and [1.0, 1.0, 1.0] both select the same colour. Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the name. To explicitly select these lists, set the colour list to either `molmol' or `x11'.
Creator: Edward d'Auvergne
Argument string: "classic"
Description: The classic style draws the backbone of a protein in a cylindrical bond style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines.
Supported data types:
(see table 10.22)
The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.
(see table 10.23)
The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.
(see table 10.24)
Apply the Molmol ribbon style.
This applies the Molmol ribbon style which is equivalent to clicking on `ribbon' in the Molmol side menu. To do this, the following commands are executed:
To apply the ribbon style to the PDB file loaded, type:
relax> molmol.
[0]
[0]ribbon(
[0]
[0])
Display the diffusion tensor PDB geometric object over the loaded PDB.
file: The name of the PDB file containing the tensor geometric object.
In executing this user function, a PDB file must have previously been loaded , a geometric object or polygon representing the Brownian rotational diffusion tensor will be overlain with the loaded PDB file and displayed within Molmol. The PDB file containing the geometric object must be created using the complementary structure.create_diff_tensor_pdb user function.
To display the diffusion tensor, the multiple commands will be executed. To overlay the structure with the diffusion tensor, everything will be selected and reoriented and moved to their original PDB frame positions:
Next the tensor PDB file is read in, selected, and the covalent bonds of the PDB CONECT records calculated:
Then only the atoms and bonds of the geometric object are selected and the `ball/stick' style applied:
The appearance is finally touched up:
View the collection of molecules from the loaded PDB file.
This will simply launch Molmol.
relax> molmol.
[0]
[0]view(
[0]
[0])
Function for creating simulation data.
method: The simulation method.
The method argument can either be set to `back_calc' or `direct', the choice of which determines the simulation type. If the values or parameters are calculated rather than minimised, this option will have no effect, hence, `back_calc' and `direct' are identical.
For error analysis, the method argument should be set to `back_calc' which will result in proper Monte Carlo simulations. The data used for each simulation is back calculated from the minimised model parameters and is randomised using Gaussian noise where the standard deviation is from the original error set. When the method is set to `back_calc', this function should only be called after the model is fully minimised.
The simulation type can be changed by setting the method argument to `direct'. This will result in simulations which cannot be used in error analysis and which are no longer Monte Carlo simulations. However, these simulations are required for certain model selection techniques (see the documentation for the model selection function for details), and can be used for other purposes. Rather than the data being back calculated from the fitted model parameters, the data is generated by taking the original data and randomising using Gaussian noise with the standard deviations set to the original error set.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations, 
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for calculating parameter errors from the Monte Carlo simulations.
prune: Legacy argument corresponding to `trim' in Art Palmer's Modelfree program.
Parameter errors are calculated as the standard deviation of the distribution of parameter values. This function should never be used if parameter values are obtained by minimisation and the simulation data are generated using the method `direct'. The reason is because only true Monte Carlo simulations can give the true parameter errors.
The prune argument is legacy code which corresponds to the `trim' option in Art Palmer's Modelfree program. To remove failed simulations, the eliminate function should be used prior to this function. Eliminating the simulations specifically identifies and removes the failed simulations whereas the prune argument will only, in a few cases, positively identify failed simulations but only if severe parameter limits have been imposed. Most failed models will pass through the pruning process and hence cause a catastrophic increase in the parameter errors. If the argument must be used, the following must be taken into account. If the values or parameters are calculated rather than minimised, the prune argument must be set to zero. The value of this argument is proportional to the number of simulations removed prior to error calculation. If prune is set to 0.0, all simulations are used for calculating errors, whereas a value of 1.0 excludes all data. In almost all cases prune must be set to zero, any value greater than zero will result in an underestimation of the error values. If a value is supplied, the lower and upper tails of the distribution of chi-squared values will be excluded from the error calculation.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for setting the initial simulation parameter values.
This function only effects where minimisation occurs and can therefore be skipped if the values or parameters are calculated rather than minimised. However, if accidentally run in this case, the results will be unaffected. It should only be called after the model or run is fully minimised. Once called, the functions `grid_search' and `minimise' will only effect the simulations and not the model parameters.
The initial values of the parameters for each simulation is set to the minimised parameters of the model. A grid search can be undertaken for each simulation instead, although this is computationally expensive and unnecessary. The minimisation function should be executed for a second time after running this function.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for turning simulations off.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for turning simulations on.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Function for setting up Monte Carlo simulations.
number: The number of Monte Carlo simulations.
This function must be called prior to any of the other Monte Carlo functions. The effect is that the number of simulations will be set and that simulations will be turned on.
For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:
1. The measured data set together with the corresponding error set should be loaded into relax.
2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.
3. To initialise and turn on Monte Carlo simulations, the number of simulations,
, needs to be set.
4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.
5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).
6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
7. Failed simulations are removed using the techniques of model elimination.
8. The model parameter errors are calculated from the distribution of simulation parameters.
Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.
An example, for model-free analysis, which includes only the functions required for implementing the above steps is:
relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.
relax> minimise(
[0]
[0]`newton') # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.
relax> minimise(
[0]
[0]`newton') # Step 6.
relax> eliminate(
[0]
[0]) # Step 7.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
An example for reduced spectral density mapping is:
relax> calc(
[0]
[0]) # Step 2.
relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.
relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.
relax> calc(
[0]
[0]) # Step 6.
relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.
Centre of mass (CoM) analysis.
pivot_point: The pivot point of the motions between the two domains.
centre: The optional argument for manually specifying the CoM of the initial position prior to the N rotations to the positions of the N states.
This function is used for analysing the domain motion information content of the N states from the N-state model. The states do not correspond to physical states, hence nothing can be extracted from the individual states. This analysis involves the calculation of the pivot to centre of mass (pivot-CoM) order parameter and subsequent cone of motions.
For the analysis, both the pivot point and centre of mass must be specified. The supplied pivot point must be a vector of floating point numbers of length 3. If the centre keyword argument is supplied, it must also be a vector of floating point numbers (of length 3). If the centre argument is not supplied, then the CoM will be calulcated from the selected parts of a previously loaded structure.
To perform an analysis where the pivot is at the origin and the CoM is set to the N-terminal domain of a previously loaded PDB file (the C-terminal domain has been deselected), type:
relax> n_state_model.
[0]
[0]CoM(
[0]
[0])
To perform an analysis where the pivot is at the origin (because the real pivot has been shifted to this position) and the CoM is at the position [0, 0, 1], type one of:
relax> n_state_model.
[0]
[0]CoM(
[0]
[0]centre=
[0]
[0][0, 0, 1])
relax> n_state_model.
[0]
[0]CoM(
[0]
[0]centre=
[0]
[0][0.0, 0.0, 1.0])
relax> n_state_model.
[0]
[0]CoM(
[0]
[0]pivot_point=
[0]
[0][0.0, 0.0, 0.0], centre=
[0]
[0][0.0, 0.0, 1.0])
Create a PDB file representing the cone models from the centre of mass (CoM) analysis.
cone_type: The type of cone model to represent.
scale: Value for scaling the pivot-CoM distance which the size of the cone defaults to.
file: The name of the PDB file.
dir: The directory where the file is located.
force: A flag which, if set to True, will overwrite the any pre-existing file.
This function creates a PDB file containing an artificial geometric structure to represent the various cone models. These models include:
The model can be selected by setting the cone_type argument to one of these strings. The cone is represented as an isotropic cone with its axis parallel to the average pivot-CoM vector, the vertex placed at the pivot point of the domain motions, and the length of the edge of the cone equal to the pivot-CoM distance multipled by the scaling argument. The resultant PDB file can subsequently read into any molecular viewer.
There are four different types of residue within the PDB. The pivot point is represented as as a single carbon atom of the residue `PIV'. The cone consists of numerous H atoms of the residue `CON'. The average pivot-CoM vector is presented as the residue `AVE' with one carbon atom positioned at the pivot and the other at the head of the vector (after scaling by the scale argument). Finally, if Monte Carlo have been performed, there will be multiple `MCC' residues representing the cone for each simulation, and multiple `MCA' residues representing the varying average pivot-CoM vector for each simulation.
To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined from the average pivot-CoM vector. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.
Eliminate the structures or states with no probability.
Simply type:
relax> n_state_model.
[0]
[0]
[0]elim_no_prob(
[0]
[0]N=
[0]
[0]8)
Set the number of states in the N-state model.
N: The number of states.
Prior to optimisation, the number of states in the N-state model can be specified. If the number of states is not set, then this parameter will be equal to the number of loaded structures.
To set up an 8-state model, type:
relax> n_state_model.
[0]
[0]number_of_states(
[0]
[0]N=
[0]
[0]8)
Set the reference domain for the `2-domain' N-state model.
ref: The domain which will act as the frame of reference. This is only valid for the `2-domain' N-state model.
Prior to optimisation of the `2-domain' N-state model, which of the two domains will act as the frame of reference must be specified. The N-states will be rotations of the other domain, so to switch the frame of reference to the other domain simply transpose the rotation matrices.
To set up a 5-state model with `C' domain being the frame of reference, type:
relax> n_state_model.
[0]
[0]ref_domain(
[0]
[0]ref=
[0]
[0]`C')
Select the N-state model type and set up the model.
model: The name of the preset N-state model.
Prior to optimisation, the N-state model type should be selected. The preset models are:
`2-domain' - The N-state model for a system of two domains, where one domain experiences a a reduced tensor.
`population' - The N-state model whereby only populations are optimised. The structures loaded into relax are assumed to be fixed. I.e. if two domains are present, the Euler angles for each state are fixed. The parameters of the model include the weight or probability for each state and the alignment tensor - {p0, p1, ..., pN, Axx, Ayy, Axy, Axz, Ayz}.
`fixed' - The N-state model whereby all motions are fixed and all populations are fixed to the set probabilities. The parameters of the model are simply the alignment tensor, {Axx, Ayy, Axy, Axz, Ayz}.
To analyse populations of states, type:
relax> n_state_model.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`populations')
Read NOESY or ROESY restraints from a file.
file: The name of the file containing the restraint data.
dir: The directory where the file is located.
proton1_col: The column containing the first proton of the NOE or ROE cross peak.
proton2_col: The column containing the second proton of the NOE or ROE cross peak.
lower_col: The column containing the lower NOE bound.
upper_col: The column containing the upper NOE bound.
sep: The column separator (the default is white space).
The format of the file will be automatically determined, for example Xplor formatted restraint files. A generically formatted file is also supported if it contains minimally four columns with the two proton names and the upper and lower bounds, as specified by the column numbers. The proton names need to be in the spin ID string format.
To read the Xplor formatted restraint file `NOE.xpl', type one of:
relax> noe.
[0]
[0]read_restraints(
[0]
[0]`NOE.
[0]
[0]xpl')
relax> noe.
[0]
[0]read_restraints(
[0]
[0]file=
[0]
[0]`NOE.
[0]
[0]xpl')
To read the generic formatted file `noes', type one of:
relax> noe.
[0]
[0]read_restraints(
[0]
[0]file=
[0]
[0]`NOE.
[0]
[0]xpl', proton1_col=
[0]
[0]0, proton2_col=
[0]
[0]1, lower_col=
[0]
[0]2, upper_col=
[0]
[0]3)
Set the steady-state NOE spectrum type for pre-loaded peak intensities.
spectrum_type: The type of steady-state NOE spectrum, one of `ref' for the reference spectrum or `sat' for the saturated spectrum.
spectrum_id: The spectrum ID string.
The spectrum type can be one of the following:
Peak intensities should be loaded before this user function via the spectrum.read_intensities user function. The intensity values will then be associated with a spectrum ID string which can be used here.
Function for creating the Modelfree4 input files.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
binary: The name of the executable Modelfree program file.
diff_search: See the Modelfree4 manual for `diffusion_search'.
sims: The number of Monte Carlo simulations.
sim_type: See the Modelfree4 manual.
trim: See the Modelfree4 manual.
steps: See the Modelfree4 manual.
constraints: A flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).
heteronuc_type: A three letter string describing the heteronucleus type, ie 15N, 13C, etc.
atom1: The symbol of the X heteronucleus in the pdb file.
atom2: The symbol of the H nucleus in the pdb file.
spin_id: The spin identification string.
The following files are created
The file `dir/run.sh' contains the single command,
`modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out',
which can be used to execute modelfree4.
If you would like to use a different Modelfree executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path infront of the binary file name.
Function for executing Modelfree4.
dir: The directory to place the files.
force: A flag which if set to True will cause the results file to be overwritten if it already exists.
binary: The name of the executable Modelfree program file.
Modelfree 4 will be executed as
$ modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out
If a PDB file is loaded and non-isotropic diffusion is selected, then the file name will be placed on the command line as `-s pdb_file_name'.
If you would like to use a different Modelfree executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path in front of the binary file name.
Function for extracting data from the Modelfree4 `mfout' star formatted file.
dir: The directory where the file `mfout' is found.
Specify which atom is the paramagnetic centre.
pos: The atomic position.
atom_id: The atom ID string.
pipe: The data pipe containing the structures to extract the centre from.
verbosity: The amount of information to print out.
fix: A flag specifying if the paramagnetic centre should be fixed during optimisation.
ave_pos: A flag specifying if the position of the atom is to be averaged across all models.
force: A flag which if True will cause the current paramagnetic centre to be overwritten.
This function is required for specifying where the paramagnetic centre is located in the loaded structure file. If no structure number is given, then the average atom position will be calculated if multiple structures are loaded.
A different set of structures than those loaded into the current data pipe can also be used to determine the position, or its average. This can be achieved by loading the alternative structures into another data pipe, and then specifying that pipe through the pipe argument.
If the ave_pos flag is set to True, the average position from all models will be used as the position of the paramagnetic centre. If False, then the positions from all structures will be used. If multiple positions are used, then a fast paramagnetic centre motion will be assumed so that PCSs for a single tensor will be calculated for each position, and the PCS values linearly averaged.
If the paramagnetic centre is the lanthanide Dysprosium which is labelled as
in a loaded PDB file, then type one of:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]`Dy')
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]atom_id=
[0]
[0]`Dy')
If the carbon atom `C1' of residue `4' in the PDB file is to be used as the paramagnetic centre, then type:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]`:4@C1')
To state that the Dy3+ atomic position is [0.136, 12.543, 4.356], type one of:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0][0.136, 12.543, 4.356])
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]pos=
[0]
[0][0.136, 12.543, 4.356])
To find an unknown paramagnetic centre, type:
relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]fix=
[0]
[0]False)
Back calculate the pseudo-contact shifts.
align_id: The alignment ID string.
Calculate the PCS Q-factor for the selected spins.
spin_id: The spin ID string for restricting to subset of all selected spins.
For this function to work, the back-calculated PCS data must first be generated by the analysis specific code. Otherwise a warning will be given.
To calculate the PCS Q-factor for only the spins `@H26', `@H27', and `@H28', type one of:
relax> pcs.
[0]
[0]
[0]calc_q_factors(
[0]
[0]`@H26 & @H27 & @H28')
relax> pcs.
[0]
[0]
[0]calc_q_factors(
[0]
[0]spin_id=
[0]
[0]`@H26 & @H27 & @H28')
Copy PCS data from pipe_from to pipe_to.
pipe_from: The name of the pipe to copy the PCS data from.
pipe_to: The name of the pipe to copy the PCS data to.
align_id: The alignment ID string.
This function will copy PCS data from `pipe_from' to `pipe_to'. If align_id is not given then all PCS data will be copied, otherwise only a specific data set will be.
To copy all PCS data from pipe `m1' to pipe `m9', type one of:
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', align_id=
[0]
[0]None)
To copy only the `Th' PCS data from `m3' to `m6', type one of:
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `Th')
relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', align_id=
[0]
[0]`Th')
Generate a correlation plot of the measured vs. the back-calculated PCSs.
format: The format of the plot data.
file: The name of the file.
dir: The directory name.
force: A flag which if True will cause the file to be overwritten.
Two formats are currently supported. If format is set to `grace', then a Grace plot file will be created. If the format arg is set to None, then a plain text list of the measured and back-calculated data will be created.
To create a Grace plot of the data, type:
relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0])
To create a plain text list of the measured and back-calculated data, type one of:
relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0]None)
relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0]format=
[0]
[0]None)
Delete the PCS data corresponding to the alignment ID.
align_id: The alignment ID string.
To delete the PCS data corresponding to align_id=`PH_gel', type:
relax> pcs.
[0]
[0]
[0]delete(
[0]
[0]`PH_gel')
Display the PCS data corresponding to the alignment ID.
align_id: The alignment ID string.
bc: A flag which if set will display the back-calculated rather than measured RDCs.
To display the `phage' PCS data, type:
relax> pcs.
[0]
[0]
[0]display(
[0]
[0]`phage')
align_id: The alignment ID string.
file: The name of the file containing the PCS data.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The PCS data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
The following commands will read the PCS data out of the file `Tb.txt' where the columns are separated by the symbol `,', and store the PCSs under the ID `Tb'.
relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', sep=
[0]
[0]`,')
To read the 15N and 1H PCSs from the file `Eu.txt', where the 15N values are in the 4
column and the 1H in the 9
, type both the following:
relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@N', res_num_col=
[0]
[0]1, data_col=
[0]
[0]4)
relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@H', res_num_col=
[0]
[0]1, data_col=
[0]
[0]9)
Set optimisation weights on the PCS data.
align_id: The alignment ID string.
spin_id: The spin ID string.
weight: The weighting value.
This function can be used to force the PCS to contribute more or less to the chi-squared optimisation statistic. The higher the value, the more importance the PCS will have.
align_id: The alignment ID string.
file: The name of the file.
dir: The directory name.
bc: A flag which if set will write out the back-calculated rather than measured RDCs.
force: A flag which if True will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory. The `align_id' argument are required for selecting which PCS data set will be written to file.
Read the Bruker Protein Dynamics Centre (PDC) file.
ri_id: The relaxation data ID string.
file: The name of the PDC file.
dir: The directory where the file is located.
This user function is used to load all of the data out of a Bruker PDC file for subsequent analysis within relax.
pipe_from: The name of the source data pipe to copy the data from.
pipe_to: The name of the target data pipe to copy the data to.
This allows the contents of a data pipe to be copied. If the source data pipe is not set, the current data pipe will be assumed. The target data pipe must not yet exist.
To copy the contents of the `m1' data pipe to the `m2' data pipe, type:
relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')
relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')
If the current data pipe is `m1', then the following command can be used:
relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m2')
Add a new data pipe to the relax data store.
pipe_name: The name of the data pipe.
pipe_type: The type of data pipe.
The data pipe name can be any string however the data pipe type can only be one of the following:
To set up a model-free analysis data pipe with the name `m5', type:
relax> pipe.
[0]
[0]
[0]create(
[0]
[0]`m5', `mf')
Print the name of the current data pipe.
To run the user function, type:
relax> pipe.
[0]
[0]
[0]current(
[0]
[0])
Delete a data pipe from the relax data store.
pipe_name: The name of the data pipe to delete.
This will permanently remove the data pipe and all of its contents from the relax data store. If the pipe name is not given, then all data pipes will be deleted.
Print a list of all the data pipes.
To run the user function, type:
relax> pipe.
[0]
[0]
[0]display(
[0]
[0])
Create a hybrid data pipe by fusing a number of other data pipes.
hybrid: The name of the hybrid data pipe to create.
pipes: An array containing the names of all data pipes to hybridise.
This user function can be used to construct hybrid models. An example of the use of a hybrid model could be if the protein consists of two independent domains. These two domains could be analysed separately, each having their own optimised diffusion tensors. The N-terminal domain data pipe could be called `N_sphere' while the C-terminal domain could be called `C_ellipsoid'. These two data pipes could then be hybridised into a single data pipe. This hybrid data pipe can then be compared via model selection to a data pipe whereby the entire protein is assumed to have a single diffusion tensor.
The requirements for data pipes to be hybridised is that the molecules, sequences, and spin systems for all the data pipes is the same, and that no spin system is allowed to be selected in two or more data pipes. The selections must not overlap to allow for rigorous statistical comparisons.
The two data pipes `N_sphere' and `C_ellipsoid' could be hybridised into a single data pipe called `mixed model' by typing:
relax> pipe.
[0]
[0]
[0]hybridise(
[0]
[0]`mixed model', [`N_sphere', `C_ellipsoid'])
relax> pipe.
[0]
[0]
[0]hybridise(
[0]
[0]hybrid=
[0]
[0]`mixed model', pipes=
[0]
[0][`N_sphere', `C_ellipsoid'])
Switch between the data pipes of the relax data store.
pipe_name: The name of the data pipe.
This will switch between the various data pipes within the relax data store.
To switch to the `ellipsoid' data pipe, type:
relax> pipe.
[0]
[0]switch(
[0]
[0]`ellipsoid')
relax> pipe.
[0]
[0]switch(
[0]
[0]pipe_name=
[0]
[0]`ellipsoid')
Apply the PyMOL cartoon style and colour by secondary structure.
This applies the PyMOL cartoon style which is equivalent to hiding everything and clicking on show cartoon. It also colours the cartoon with red helices, yellow strands, and green loops. The following commands are executed:
where file is the file name without the `.pdb' extension.
To apply this user function, type:
relax> pymol.
[0]
[0]
[0]cartoon(
[0]
[0])
Clear the PyMOL command history.
This will clear the Pymol history from memory.
Execute a user supplied PyMOL command.
command: The PyMOL command to execute.
This allows PyMOL commands to be passed to the program. This can be useful for automation or scripting.
To reinitialise the PyMOL instance, type:
relax> pymol.
[0]
[0]
[0]command(
[0]
[0]"reinitialise")
Display the cone PDB geometric object.
file: The name of the PDB file containing the cone geometric object.
The PDB file containing the geometric object must be created using the complementary frame_order.cone_pdb or
_state_model.cone_pdb user functions.
The cone PDB file is read in using the command:
The average CoM-pivot point vector, the residue `AVE' is displayed using the commands:
The cone object, the residue `CON', is displayed using the commands:
Execute PyMOL macros.
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
This allows spin specific values to be mapped to a structure through PyMOL macros. Currently only the `classic' style, which is described below, is available.
To map the order parameter values,
, onto the structure using the classic style, type:
relax> pymol.
[0]
[0]macro_apply(
[0]
[0]`s2')
relax> pymol.
[0]
[0]macro_apply(
[0]
[0]data_type=
[0]
[0]`s2')
relax> pymol.
[0]
[0]macro_apply(
[0]
[0]data_type=
[0]
[0]`s2', style=
[0]
[0]"classic")
The values are coloured based on a linear colour gradient which is specified through the starting and ending colours. These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, `white' and [1.0, 1.0, 1.0] both select the same colour. Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the name. To explicitly select these lists, set the colour list to either `molmol' or `x11'.
Creator: Edward d'Auvergne
Argument string: "classic"
Description: The classic style draws the backbone of a protein in a cylindrical bond style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines.
Supported data types:
(see table 10.25)
The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.
(see table 10.26)
The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.
(see table 10.27)
Open and execute the PyMOL macro file.
file: The name of the PyMOL macro file.
dir: The directory name.
This user function is for opening and running a PyMOL macro located within a text file.
To execute the macro file `s2.pml' located in the directory `pymol', type:
relax> pymol.
[0]
[0]macro_run(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]pml')
relax> pymol.
[0]
[0]macro_run(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]pml', dir=
[0]
[0]`pymol')
Create PyMOL macros.
data_type: The data type to map to the structure.
style: The style of the macro.
colour_start: The starting colour, either an array or string, of the linear colour gradient.
colour_end: The ending colour, either an array or string, of the linear colour gradient.
colour_list: The list of colours to match the start and end strings.
file: The optional name of the file.
dir: The optional directory to save the file to.
force: A flag which, if set to True, will cause the file to be overwritten.
This allows residues specific values to be mapped to a structure through the creation of a PyMOL macro which can be executed in PyMOL by clicking on `File, Macro, Execute User...'. Currently only the `classic' style, which is described below, is available.
To create a PyMOL macro mapping the order parameter values,
, onto the structure using the classic style, type:
relax> pymol.
[0]
[0]macro_write(
[0]
[0]`s2')
relax> pymol.
[0]
[0]macro_write(
[0]
[0]data_type=
[0]
[0]`s2')
relax> pymol.
[0]
[0]macro_write(
[0]
[0]data_type=
[0]
[0]`s2', style=
[0]
[0]"classic", file=
[0]
[0]`s2.
[0]
[0]pml', dir=
[0]
[0]`pymol')
The values are coloured based on a linear colour gradient which is specified through the starting and ending colours. These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, `white' and [1.0, 1.0, 1.0] both select the same colour. Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.
When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the name. To explicitly select these lists, set the colour list to either `molmol' or `x11'.
Creator: Edward d'Auvergne
Argument string: "classic"
Description: The classic style draws the backbone of a protein in a cylindrical bond style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines.
Supported data types:
(see table 10.28)
The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.
(see table 10.29)
The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.
(see table 10.30)
Display the diffusion tensor PDB geometric object over the loaded PDB.
file: The name of the PDB file containing the tensor geometric object.
In executing this user function, a PDB file must have previously been loaded into this data pipe a geometric object or polygon representing the Brownian rotational diffusion tensor will be overlain with the loaded PDB file and displayed within PyMOL. The PDB file containing the geometric object must be created using the complementary structure.create_diff_tensor_pdb user function.
The tensor PDB file is read in using the command:
The centre of mass residue `COM' is displayed using the commands:
The axes of the diffusion tensor, the residue `AXS', is displayed using the commands:
The simulation axes, the residues `SIM', are displayed using the commands:
Display the PDB file representation of the XH vector distribution.
file: The name of the PDB file containing the vector distribution.
A PDB file of the macromolecule must have previously been loaded as the vector distribution will be overlain with the macromolecule within PyMOL. The PDB file containing the vector distribution must be created using the complementary structure.create_vector_dist user function.
The vector distribution PDB file is read in using the command:
View the collection of molecules from the loaded PDB file.
This will simply launch Pymol.
relax> pymol.
[0]
[0]view(
[0]
[0])
Back calculate RDCs.
align_id: The alignment ID string.
Calculate the RDC Q-factor for the selected spins.
spin_id: The spin ID string for restricting to subset of all selected spins.
For this function to work, the back-calculated RDC data must first be generated by the analysis specific code. Otherwise a warning will be given.
To calculate the RDC Q-factor for only the spins `@H26', `@H27', and `@H28', type one of:
relax> rdc.
[0]
[0]
[0]calc_q_factors(
[0]
[0]`@H26 & @H27 & @H28')
relax> rdc.
[0]
[0]
[0]calc_q_factors(
[0]
[0]spin_id=
[0]
[0]`@H26 & @H27 & @H28')
Copy RDC data from pipe_from to pipe_to.
pipe_from: The name of the pipe to copy the RDC data from.
pipe_to: The name of the pipe to copy the RDC data to.
align_id: The alignment ID string.
This function will copy RDC data from `pipe_from' to `pipe_to'. If align_id is not given then all RDC data will be copied, otherwise only a specific data set will be.
To copy all RDC data from pipe `m1' to pipe `m9', type one of:
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', align_id=
[0]
[0]None)
To copy only the `Th' RDC data from `m3' to `m6', type one of:
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `Th')
relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', align_id=
[0]
[0]`Th')
Generate a correlation plot of the measured vs. the back-calculated RDCs.
format: The format of the plot data.
file: The name of the file.
dir: The directory name.
force: A flag which if True will cause the file to be overwritten.
Two formats are currently supported. If format is set to `grace', then a Grace plot file will be created. If the format arg is set to None, then a plain text list of the measured and back-calculated data will be created.
To create a Grace plot of the data, type:
relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0])
To create a plain text list of the measured and back-calculated data, type one of:
relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0]None)
relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0]format=
[0]
[0]None)
Delete the RDC data corresponding to the alignment ID.
align_id: The alignment ID string.
To delete the RDC data corresponding to align_id=`PH_gel', type:
relax> rdc.
[0]
[0]
[0]delete(
[0]
[0]`PH_gel')
Display the RDC data corresponding to the alignment ID.
align_id: The alignment ID string.
bc: A flag which if set will display the back-calculated rather than measured RDCs.
To display the `phage' RDC data, type:
relax> rdc.
[0]
[0]
[0]display(
[0]
[0]`phage')
align_id: The alignment ID string.
file: The name of the file containing the RDC data.
dir: The directory where the file is located.
data_type: Whether the RDC data is in the D or 2D format.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
neg_g_corr: A flag which is used to correct for the negative gyromagnetic ratio of 15N.
The data_type argument is used to specify how the RDC is defined. It is a string which can be set to two values:
Internally, relax uses the D notation. Therefore if set to `2D', the values will be doubled when read in.
If neg_g_corr is set to True, a sign inversion will be applied to all RDC values to be loaded. This is sometimes needed for 15N if the data is not compensated for the negative gyromagnetic ratio.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
The following commands will read the RDC data out of the file `Tb.txt' where the columns are separated by the symbol `,', and store the RDCs under the ID `Tb':
relax> rdc.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', sep=
[0]
[0]`,')
If the individual spin RDC errors are located in the file `rdc_err.txt' in column number 5, then to read these values into relax, assuming J + D was measured, type one of:
relax> rdc.
[0]
[0]read(
[0]
[0]`phage', `rdc_err.
[0]
[0]txt', data_type=
[0]
[0]`D', error_col=
[0]
[0]5)
relax> rdc.
[0]
[0]read(
[0]
[0]align_id=
[0]
[0]`phage', file=
[0]
[0]`rdc_err.
[0]
[0]txt', data_type=
[0]
[0]`D', error_col=
[0]
[0]5)
If the RDCs correspond to the `N' spin and other spin types such as 1H, 13C, etc. are loaded into relax, then type:
relax> rdc.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@N')
Set optimisation weights on the RDC data.
align_id: The alignment ID string.
spin_id: The spin ID string.
weight: The weighting value.
This function can be used to force the RDC to contribute more or less to the chi-squared optimisation statistic. The higher the value, the more importance the RDC will have.
align_id: The alignment ID string.
file: The name of the file.
dir: The directory name.
bc: A flag which if set will write out the back-calculated rather than measured RDCs.
force: A flag which if True will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory. The `align_id' argument are required for selecting which RDC data set will be written to file.
Back calculate the relaxation data at the given frequency.
ri_id: The relaxation data ID string.
ri_type: The relaxation data type, ie `R1', `R2', or `NOE'.
frq: The spectrometer frequency in Hz.
This allows relaxation data of the given type and frequency to be back calculated from the model parameter values.
Copy relaxation data from one pipe to another.
pipe_from: The name of the pipe to copy the relaxation data from.
pipe_to: The name of the pipe to copy the relaxation data to.
ri_id: The relaxation data ID string.
This will copy relaxation data from one data pipe to another. If the relaxation ID data string is not given then all relaxation data will be copied, otherwise only a specific data set will be copied.
To copy all relaxation data from pipe `m1' to pipe `m9', type one of:
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', ri_id=
[0]
[0]None)
To copy only the NOE relaxation data with the ID string of `NOE_800' from `m3' to `m6', type one of:
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `NOE_800')
relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', ri_id=
[0]
[0]`NOE_800')
Delete the data corresponding to the relaxation data ID string.
ri_id: The relaxation data ID string.
The relaxation data corresponding to the given relaxation data ID string will be removed from the current data pipe.
To delete the relaxation data corresponding to the ID `NOE_600', type:
relax> relax_data.
[0]
[0]
[0]delete(
[0]
[0]`NOE_600')
Display the data corresponding to the relaxation data ID string.
ri_id: The relaxation data ID string.
To display the NOE relaxation data at 600 MHz with the ID string `NOE_600', type:
relax> relax_data.
[0]
[0]
[0]display(
[0]
[0]`NOE_600')
Specify the type of peak intensity measurement used - 
.e. height or volume.
ri_id: The relaxation data ID string.
type: The peak intensity type.
This is essential for BMRB data deposition. It is used to specify whether peak heights or peak volumes were measured. The two currently allowed values for the type argument are `height' and `volume'.
Read R
, R
, or NOE relaxation data from a file.
ri_id: The relaxation data ID string. This must be a unique identifier.
ri_type: The relaxation data type,
.e. `R1', `R2', or `NOE'.
frq: The exact proton frequency of the spectrometer in Hertz. See the `sfrq' parameter in the Varian procpar file or the `SFO1' parameter in the Bruker acqus file.
file: The name of the file containing the relaxation data.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The relaxation data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the molecule name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin ID string can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
The following commands will read the protein NOE relaxation data collected at 600 MHz out of a file called `noe.600.out' where the residue numbers, residue names, data, errors are in the first, second, third, and forth columns respectively.
relax> relax_data.
[0]
[0]read(
[0]
[0]`NOE_600', `NOE', 599.7 * 1e6, `noe.600.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4)
relax> relax_data.
[0]
[0]read(
[0]
[0]ri_id=
[0]
[0]`NOE_600', ri_type=
[0]
[0]`NOE', frq=
[0]
[0]600.0 * 1e6, file=
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4)
The following commands will read the R
data out of the file `r2.out' where the residue numbers, residue names, data, errors are in the second, third, fifth, and sixth columns respectively. The columns are separated by commas.
relax> relax_data.
[0]
[0]read(
[0]
[0]`R2_800', `R2', 8.0 * 1e8, `r2.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]3, data_col=
[0]
[0]5, error_col=
[0]
[0]6, sep=
[0]
[0]`,')
relax> relax_data.
[0]
[0]read(
[0]
[0]ri_id=
[0]
[0]`R2_800', ri_type=
[0]
[0]`R2', frq=
[0]
[0]8.0*1e8, file=
[0]
[0]`r2.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]3, data_col=
[0]
[0]5, error_col=
[0]
[0]6, sep=
[0]
[0]`,')
The following commands will read the R
data out of the file `r1.out' where the columns are separated by the symbol `%'
relax> relax_data.
[0]
[0]read(
[0]
[0]`R1_300', `R1', 300.1 * 1e6, `r1.
[0]
[0]out', sep=
[0]
[0]`%')
Specify the temperature calibration method used.
ri_id: The relaxation data ID string.
method: The calibration method.
This is essential for BMRB data deposition. The currently allowed methods are:
Other strings will be accepted if supplied.
Specify the temperature control method used.
ri_id: The relaxation data ID string.
method: The control method.
This is essential for BMRB data deposition. The currently allowed methods are:
Write relaxation data to a file.
ri_id: The relaxation data ID string.
file: The name of the file.
dir: The directory name.
force: A flag which if True will cause the file to be overwritten.
If no directory name is given, the file will be placed in the current working directory. The relaxation data ID string is required for selecting which relaxation data to write to file.
Set the relaxation delay time associated with each spectrum.
time: The time, in seconds, of the relaxation period.
spectrum_id: The spectrum identification string.
Peak intensities should be loaded before calling this user function via the spectrum.read_intensities user function. The intensity values will then be associated with a spectrum identifier. To associate each spectrum identifier with a time point in the relaxation curve prior to optimisation, this user function should be called.
Select the relaxation curve type.
model: The type of relaxation curve to fit.
The supported relaxation experiments include the default two parameter exponential fit, selected by setting the `fit_type' argument to `exp', and the three parameter inversion recovery experiment in which the peak intensity limit is a non-zero value, selected by setting the argument to `inv'.
The parameters of these two models are
Reset relax.
All of the data of the relax data storage object will be erased and hence relax will return to its initial state.
Copy all data associated with a residue.
pipe_from: The data pipe containing the residue from which the data will be copied. This defaults to the current data pipe.
res_from: The residue ID string of the residue to copy the data from.
pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.
res_to: The residue ID string of the residue to copy the data to.
This will copy all the data associated with the identified residue to the new, non-existent residue. The new residue cannot currently exist.
To copy the residue data from residue 1 to the new residue 2, type:
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`:1', res_to=
[0]
[0]`:2')
To copy residue 1 of the molecule `Old mol' to residue 5 of the molecule `New mol', type:
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`#Old mol:1', res_to=
[0]
[0]`#New mol:5')
To copy the residue data of residue 1 from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`:1', pipe_to=
[0]
[0]`m2')
relax> residue.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', res_from=
[0]
[0]`:1', pipe_to=
[0]
[0]`m2', res_to=
[0]
[0]`:1')
Create a new residue.
res_num: The residue number.
res_name: The name of the residue.
mol_name: The name of the molecule to add the residue to.
Using this, a new sequence can be generated without using the sequence user functions. However if the sequence already exists, the new residue will be added to the end of the residue list (the residue numbers of this list need not be sequential). The same residue number cannot be used more than once. A corresponding single spin system will be created for this residue. The spin system number and name or additional spin systems can be added later if desired.
The following sequence of commands will generate the sequence 1 ALA, 2 GLY, 3 LYS:
relax> residue.
[0]
[0]
[0]create(
[0]
[0]1, `ALA')
relax> residue.
[0]
[0]
[0]create(
[0]
[0]2, `GLY')
relax> residue.
[0]
[0]
[0]create(
[0]
[0]3, `LYS')
Delete residues from the current data pipe.
res_id: The residue ID string.
This can be used to delete a single or sets of residues. See the ID string documentation for more information. If spin system/atom ids are included a RelaxError will be raised.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Display information about the residue(s).
res_id: The residue ID string.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Name the residues.
res_id: The residue ID string corresponding to one or more residues.
name: The new name.
force: A flag which if True will cause the residue to be renamed.
This simply allows residues to be named (or renamed).
The following sequence of commands will rename the sequence {1 ALA, 2 GLY, 3 LYS} to {1 XXX, 2 XXX, 3 XXX}:
relax> residue.
[0]
[0]name(
[0]
[0]`:1', `XXX', force=
[0]
[0]True)
relax> residue.
[0]
[0]name(
[0]
[0]`:2', `XXX', force=
[0]
[0]True)
relax> residue.
[0]
[0]name(
[0]
[0]`:3', `XXX', force=
[0]
[0]True)
Alternatively:
relax> residue.
[0]
[0]name(
[0]
[0]`:1,2,3', `XXX', force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Number the residues.
res_id: The residue ID string corresponding to a single residue.
number: The new residue number.
force: A flag which if True will cause the residue to be renumbered.
This simply allows residues to be numbered. The new number cannot correspond to an existing residue.
The following sequence of commands will renumber the sequence {1 ALA, 2 GLY, 3 LYS} to {101 ALA, 102 GLY, 103 LYS}:
relax> residue.
[0]
[0]number(
[0]
[0]`:1', 101, force=
[0]
[0]True)
relax> residue.
[0]
[0]number(
[0]
[0]`:2', 102, force=
[0]
[0]True)
relax> residue.
[0]
[0]number(
[0]
[0]`:3', 103, force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
This will print to screen (STDOUT) the results contained within the current data pipe.
file: The name of the file to read results from.
dir: The directory where the file is located.
This function is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found the file with `.bz2' appended followed by the file name with `.gz' appended will be searched for.
file: The name of the file to output results to. The default is `results'. Optionally this can be a file object, or any object with a write() method.
dir: The directory name.
compress_type: The type of compression to use when creating the file.
force: A flag which if True will cause the results file to be overwritten.
To place the results file in the current working directory in the prompt and scripting modes, set dir to None. If dir is set to the special name `pipe_name', then the results file will be placed into a directory with the same name as the current data pipe.
The default behaviour of this function is to compress the file using bzip2 compression. If the extension `.bz2' is not included in the file name, it will be added. The compression can, however, be changed to either no compression or gzip compression. This is controlled by the compression type which can be set to
The complementary read function will automatically handle the compressed files.
Select all spins.
This will select all spins, irregardless of their current state.
To select all spins, simply type:
relax> select.
[0]
[0]
[0]all(
[0]
[0])
Select the spins contained in a file.
file: The name of the file containing the list of spins to select.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
boolean: The boolean operator specifying how spins should be selected.
change_all: A flag specifying if all other spins should be changed.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the molecule name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin ID string can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
Empty lines and lines beginning with a hash are ignored.
The `change all' flag default is False meaning that all spins currently either selected or deselected will remain that way. Setting this to True will cause all spins not specified in the file to be deselected.
To select all residues listed with residue numbers in the first column of the file `isolated_peaks', type one of:
relax> select.
[0]
[0]read(
[0]
[0]`isolated_peaks', res_num_col=
[0]
[0]1)
relax> select.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`isolated_peaks', res_num_col=
[0]
[0]1)
To select the spins in the second column of the relaxation data file `r1.600' while deselecting all other spins, for example type:
relax> select.
[0]
[0]read(
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
relax> select.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)
The boolean operator can be used to change how spin systems are selected. The allowed values are: `OR', `NOR', `AND', `NAND', `XOR', `XNOR'. The following table details how the selections will occur for the different boolean operators.
(see table 10.31)
Reversal of the spin selection for the given spins.
spin_id: The spin ID string.
By supplying the spin ID string, a subset of spins can have their selection status reversed.
To select all currently deselected spins and deselect those which are selected type:
relax> select.
[0]
[0]reverse(
[0]
[0])
Select specific spins.
spin_id: The spin ID string.
boolean: The boolean operator specifying how spins should be selected.
change_all: A flag specifying if all other spins should be changed.
The `change all' flag default is False meaning that all spins currently either selected or deselected will remain that way. Setting this to True will cause all spins not specified by the spin ID string to be selected.
To select only glycines and alanines, assuming they have been loaded with the names GLY and ALA, type one of:
relax> select.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:GLY|:ALA')
To select residue 5 CYS in addition to the currently selected residues, type one of:
relax> select.
[0]
[0]spin(
[0]
[0]`:5')
relax> select.
[0]
[0]spin(
[0]
[0]`:5&:CYS')
relax> select.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:5&:CYS')
The boolean operator can be used to change how spin systems are selected. The allowed values are: `OR', `NOR', `AND', `NAND', `XOR', `XNOR'. The following table details how the selections will occur for the different boolean operators.
(see table 10.32)
Copy the molecule, residue, and spin sequence data from one data pipe to another.
pipe_from: The name of the data pipe to copy the sequence data from.
pipe_to: The name of the data pipe to copy the sequence data to.
This will copy the sequence data between data pipes. The destination data pipe must not contain any sequence data. If the source and destination pipes are not specified, then both will default to the current data pipe (hence providing one is essential).
To copy the sequence from the data pipe `m1' to the current data pipe, type:
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]`m1')
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1')
To copy the sequence from the current data pipe to the data pipe `m9', type:
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m9')
To copy the sequence from the data pipe `m1' to `m2', type:
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')
relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')
Display sequences of molecules, residues, and/or spins.
sep: The column separator (the default of None corresponds to white space).
mol_name_flag: A flag whic if True will cause the molecule name column to be shown.
res_num_flag: A flag whic if True will cause the residue number column to be shown.
res_name_flag: A flag whic if True will cause the residue name column to be shown.
spin_num_flag: A flag whic if True will cause the spin number column to be shown.
spin_name_flag: A flag whic if True will cause the spin name column to be shown.
Read the molecule, residue, and spin sequence from a file.
file: The name of the file containing the sequence data.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the molecule name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin ID string can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
The following commands will read protein backbone 15N sequence data out of a file called `seq' where the residue numbers and names are in the first and second columns respectively:
relax> sequence.
[0]
[0]read(
[0]
[0]`seq')
relax> sequence.
[0]
[0]read(
[0]
[0]`seq', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`seq', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, sep=
[0]
[0]None)
The following commands will read the residue sequence out of the file `noe.out' which also contains the NOE values:
relax> sequence.
[0]
[0]read(
[0]
[0]`noe.
[0]
[0]out')
relax> sequence.
[0]
[0]read(
[0]
[0]`noe.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`noe.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)
The following commands will read the sequence out of the file `noe.600.out' where the residue numbers are in the second column, the names are in the sixth column and the columns are separated by commas:
relax> sequence.
[0]
[0]read(
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]6, sep=
[0]
[0]`,')
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]6, sep=
[0]
[0]`,')
The following commands will read the RNA residues and atoms (including C2, C5, C6, C8, N1, and N3) from the file `500.NOE', where the residue number, residue name, spin number, and spin name are in the first to fourth columns respectively:
relax> sequence.
[0]
[0]read(
[0]
[0]`500.
[0]
[0]NOE', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, spin_num_col=
[0]
[0]3, spin_name_col=
[0]
[0]4)
relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`500.
[0]
[0]NOE', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, spin_num_col=
[0]
[0]3, spin_name_col=
[0]
[0]4)
Write the molecule, residue, and spin sequence to a file.
file: The name of the file.
dir: The directory name.
sep: The column separator (the default of None corresponds to white space).
mol_name_flag: A flag which if True will cause the molecule name column to be shown.
res_num_flag: A flag which if True will cause the residue number column to be shown.
res_name_flag: A flag which if True will cause the residue name column to be shown.
spin_num_flag: A flag which if True will cause the spin number column to be shown.
spin_name_flag: A flag which if True will cause the spin name column to be shown.
force: A flag which if True will cause the file to be overwritten.
Write the sequence data to file. If no directory name is given, the file will be placed in the current working directory.
Set the baseplane RMSD of a given spin in a spectrum for error analysis.
error: The baseplane RMSD error value.
spectrum_id: The spectrum ID string.
spin_id: The spin ID string.
The spectrum ID identifies the spectrum associated with the error and must correspond to a previously loaded set of intensities. If the spin ID is unset, then the error value for all spins will be set to the supplied value.
Delete the spectral data corresponding to the spectrum ID string.
spectrum_id: The unique spectrum ID string.
The spectral data corresponding to the given spectrum ID string will be removed from the current data pipe.
To delete the peak height data corresponding to the ID `R1 ncyc5', type:
relax> spectrum.
[0]
[0]
[0]delete(
[0]
[0]`R1 ncyc5')
Perform an error analysis for peak intensities.
This user function must only be called after all peak intensities have been loaded and all other necessary spectral information set. This includes the baseplane RMSD and the number of points used in volume integration, both of which are only used if spectra have not been replicated.
Six different types of error analysis are supported depending on whether peak heights or volumes are supplied, whether noise is determined from replicated spectra or the RMSD of the baseplane noise, and whether all spectra or only a subset have been duplicated. These are:
(see table 10.33)
When none of the spectra have been replicated, then the peak height errors are calculated using the RMSD of the baseplane noise, the value of which is set by the spectrum.baseplane_rmsd() user function. This results in a different error per peak per spectrum. The standard deviation error measure for the peak height, sigma_I, is set to the RMSD value.
When spectra are replicated, the variance for a single spin at a single replicated spectra set is calculated by the formula
sigma^2 = sum({Ii - Iav}^2) / (n - 1) ,
where sigma^2 is the variance, sigma is the standard deviation,
is the size of the replicated spectra set with
being the corresponding index, Ii is the peak intensity for spectrum
, and Iav is the mean over all spectra
.e. the sum of all peak intensities divided by
.
As the value of
in the above equation is always very low since normally only a couple of spectra are collected per replicated spectra set, the variance of all spins is averaged for a single replicated spectra set. Although this results in all spins having the same error, the accuracy of the error estimate is significantly improved.
If there are in addition to the replicated spectra loaded peak intensities which only consist of a single spectrum,
.e. not all spectra are replicated, then the variances of replicated replicated spectra sets will be averaged. This will be used for the entire experiment so that there will be only a single error value for all spins and for all spectra.
If all spectra are collected in duplicate (triplicate or higher number of spectra are supported), the each replicated spectra set will have its own error estimate. The error for a single peak is calculated as when partially replicated spectra are collected, and these are again averaged to give a single error per replicated spectra set. However as all replicated spectra sets will have their own error estimate, variance averaging across all spectra sets will not be performed.
The method of error analysis when no spectra have been replicated and peak volumes are used is highly dependent on the integration method. Many methods simply sum the number of points within a fixed region, either a box or oval object. The number of points used, N, must be specified by another user function in this class. Then the error is simply given by the sum of variances:
sigma_vol^2 = sigma_i^2 * N,
where sigma_vol is the standard deviation of the volume, sigma_i is the standard deviation of a single point assumed to be equal to the RMSD of the baseplane noise, and N is the total number of points used in the summation integration method. For a box integration method, this converts to the Nicholson, Kay, Baldisseri, Arango, Young, Bax, and Torchia (1992) Biochemistry, 31: 5253-5263 equation:
sigma_vol = sigma_i * sqrt(n*m),
where
and 
are the dimensions of the box. Note that a number of programs, for example peakint (http://hugin.ethz.ch/wuthrich/software/xeasy/xeasy_m15.html) does not use all points within the box. And if the number N can not be determined, this category of error analysis is not possible.
Also note that non-point summation methods, for example when line shape fitting is used to determine peak volumes, the equations above cannot be used. Hence again this category of error analysis cannot be used. This is the case for one of the three integration methods used by Sparky (http://www.cgl.ucsf.edu/home/sparky/manual/peaks.html#Integration). And if fancy techniques are used, for example as Cara does to deconvolute overlapping peaks (http://www.cara.ethz.ch/Wiki/Integration), this again makes this error analysis impossible.
When peak volumes are measured by any integration method and a few of the spectra are replicated, then the intensity errors are calculated identically as described in the `Peak heights with partially replicated spectra' section above.
With all spectra replicated and again using any integration methodology, the intensity errors can be calculated as described in the `Peak heights with all spectra replicated' section above.
Set the number of summed points used in volume integration of a given spin in a spectrum.
N: The number of points used by the summation volume integration method.
spectrum_id: The spectrum ID string.
spin_id: The spin ID string.
For a complete description of which integration methods and how many points N are used for different integration techniques, please see the spectrum.error_analysis user function documentation.
The spectrum ID identifies the spectrum associated with the value of N and must correspond to a previously loaded set of intensities. If the spin ID is unset, then the number of summed points for all spins will be set to the supplied value.
Read peak intensities from a file.
file: The name of the file containing the intensity data.
dir: The directory where the file is located.
spectrum_id: The unique spectrum ID string.
heteronuc: The name of the heteronucleus as specified in the peak intensity file.
proton: The name of the proton as specified in the peak intensity file.
int_method: The integration method.
int_col: The optional column containing the peak intensity data (used by the generic intensity file format, or if the intensities are in a non-standard column).
spin_id_col: The spin ID string column used by the generic intensity file format (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column used by the generic intensity file format (alternative to the spin ID column).
res_num_col: The residue number column used by the generic intensity file format (alternative to the spin ID column).
res_name_col: The residue name column used by the generic intensity file format (alternative to the spin ID column).
spin_num_col: The spin number column used by the generic intensity file format (alternative to the spin ID column).
spin_name_col: The spin name column used by the generic intensity file format (alternative to the spin ID column).
sep: The column separator used by the generic intensity format (the default is white space).
spin_id: The spin ID string used by the generic intensity file format to restrict the loading of data to certain spin subsets.
ncproc: The Bruker specific FID intensity scaling factor.
The peak intensity can either be from peak heights or peak volumes.
The spectrum ID is a label which is subsequently utilised by other user functions. If this identifier matches that of a previously loaded set of intensities, then this indicates a replicated spectrum.
The heteronucleus and proton should be set respectively to the name of the heteronucleus and proton in the file. Only those lines which match these labels will be used.
The integration method is required for the subsequent error analysis. When peak heights are measured, this should be set to `height'. Volume integration methods are a bit varied and hence two values are accepted. If the volume integration involves pure point summation, with no deconvolution algorithms or other methods affecting peak heights, then the value should be set to `point sum'. All other volume integration methods, e.g. line shape fitting, the value should be set to `other'.
If a series of intensities extracted from Bruker FID files processed in Topspin or XWinNMR are to be compared, the ncproc parameter may need to be supplied. This is because this FID is stored using integer representation and is scaled using ncproc to avoid numerical truncation artifacts. If two spectra have significantly different maximal intensities, then ncproc will be different for both. The intensity scaling is binary,
.e. 2**ncproc. Therefore if spectrum A has an ncproc of 6 and and spectrum B a value of 7, then a reference intensity in B will be double that of A. Internally, relax stores the intensities scaled by 2**ncproc.
To read the reference and saturated spectra peak heights from the Sparky formatted files `ref.list' and `sat.list', type:
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`ref.
[0]
[0]list', spectrum_id=
[0]
[0]`ref')
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`sat.
[0]
[0]list', spectrum_id=
[0]
[0]`sat')
To read the reference and saturated spectra peak heights from the XEasy formatted files `ref.text' and `sat.text', type:
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`ref.
[0]
[0]text', spectrum_id=
[0]
[0]`ref')
relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`sat.
[0]
[0]text', spectrum_id=
[0]
[0]`sat')
The peak list or intensity file will be automatically determined.
Sparky peak list: The file should be a Sparky peak list saved after typing the command `lt'. The default is to assume that columns 0, 1, 2, and 3 (1
, 2
, 3
, and 4
) contain the Sparky assignment, w1, w2, and peak intensity data respectively. The frequency data w1 and w2 are ignored while the peak intensity data can either be the peak height or volume displayed by changing the window options. If the peak intensity data is not within column 3, set the integration column to the appropriate number (column numbering starts from 0 rather than 1).
XEasy peak list: The file should be the saved XEasy text window output of the list peak entries command, `tw' followed by `le'. As the columns are fixed, the peak intensity column is hardwired to number 10 (the 11
column) which contains either the peak height or peak volume data. Because the columns are fixed, the integration column number will be ignored.
NMRView: The file should be a NMRView peak list. The default is to use column 16 (which contains peak heights) for peak intensities. To use use peak volumes (or evolumes), int_col must be set to 15.
Generic intensity file: This is a generic format which can be created by scripting to support non- supported peak lists. It should contain in the first few columns enough information to identify the spin. This can include columns for the molecule name, residue number, residue name, spin number, and spin name. Alternatively a spin ID string column can be used. The peak intensities can be placed in another column specified by the integration column number. Intensities from multiple spectra can be placed into different columns, and these can then be specified simultaneously by setting the integration column value to a list of columns. This list must be matched by setting the spectrum ID to a list of the same length. If columns are delimited by a character other than whitespace, this can be specified with the column separator. The spin ID can be used to restrict the loading to specific spin subsets.
Specify which spectra are replicates of each other.
spectrum_ids: The list of replicated spectra ID strings.
This is used to identify which of the loaded spectra are replicates of each other. Specifying the replicates is essential for error analysis if the baseplane RMSD has not been supplied.
To specify that the NOE spectra labelled `ref1', `ref2', and `ref3' are the same spectrum replicated, type one of:
relax> spectrum.
[0]
[0]replicated(
[0]
[0][`ref1', `ref2', `ref3'])
relax> spectrum.
[0]
[0]replicated(
[0]
[0]spectrum_ids=
[0]
[0][`ref1', `ref2', `ref3'])
To specify that the two R
spectra `ncyc2' and `ncyc2
' are the same time point, type:
relax> spectrum.
[0]
[0]replicated(
[0]
[0][`ncyc2', `ncyc2b'])
Copy all data associated with a spin.
pipe_from: The data pipe containing the spin from which the data will be copied. This defaults to the current data pipe.
spin_from: The spin identifier string of the spin to copy the data from.
pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.
spin_to: The spin identifier string of the spin to copy the data to.
This will copy all the data associated with the identified spin to the new, non-existent spin. The new spin must not already exist.
To copy the spin data from spin 1 to the new spin 2, type:
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`@1', spin_to=
[0]
[0]`@2')
To copy spin 1 of the molecule `Old mol' to spin 5 of the molecule `New mol', type:
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`#Old mol@1', spin_to=
[0]
[0]`#New mol@5')
To copy the spin data of spin 1 from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`@1', pipe_to=
[0]
[0]`m2')
relax> spin.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', spin_from=
[0]
[0]`@1', pipe_to=
[0]
[0]`m2', spin_to=
[0]
[0]`@1')
Create a new spin.
spin_num: The spin number.
spin_name: The name of the spin.
res_num: The number of the residue to add the spin to.
res_name: The name of the residue to add the spin to.
mol_name: The name of the molecule to add the spin to.
This will add a new spin data container to the relax data storage object. The same spin number cannot be used more than once.
The following sequence of commands will generate the sequence 1 C4, 2 C9, 3 C15:
relax> spin.
[0]
[0]
[0]create(
[0]
[0]1, `C4')
relax> spin.
[0]
[0]
[0]create(
[0]
[0]2, `C9')
relax> spin.
[0]
[0]
[0]create(
[0]
[0]3, `C15')
Create a spin system representing a pseudo-atom.
spin_name: The name of the pseudo-atom spin.
spin_num: The spin number.
res_id: The molecule and residue ID string identifying the position to add the pseudo-spin to.
members: A list of the atoms (as spin ID strings) that the pseudo-atom is composed of.
averaging: The positional averaging technique.
This will create a spin data container representing a number of pre-existing spin containers as a pseudo-atom. The optional spin number must not already exist.
The following will create the pseudo-atom named `Q9' consisting of the protons `@H16', `@H17', `@H18':
relax> spin.
[0]
[0]
[0]create_pseudo(
[0]
[0]`Q9', members=
[0]
[0][`@H16', `@H17', `@H18'])
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
spin_id: The spin identifier string.
This can be used to delete a single or sets of spins. See the identification string documentation below for more information.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Display information about the spin(s).
spin_id: The spin identification string.
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Set the element type of the spin.
spin_id: The spin identification string corresponding to one or more spins.
element: The IUPAC element name.
force: A flag which if True will cause the element to be changed.
This allows the element type of the spins to be set.
The set all spins of residue 1 to be carbons, type one of:
relax> spin.
[0]
[0]
[0]element(
[0]
[0]`@1', `C', force=
[0]
[0]True)
relax> spin.
[0]
[0]
[0]element(
[0]
[0]spin_id=
[0]
[0]`@1', element=
[0]
[0]`C', force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Name the spins.
spin_id: The spin identification string corresponding to one or more spins.
name: The new name.
force: A flag which if True will cause the spin to be renamed.
This simply allows spins to be named (or renamed). Spin naming often essential. For example when reading Sparky peak list files, then the spin name must match that in the file.
The following sequence of commands will rename the sequence {1 C1, 2 C2, 3 C3} to {1 C11, 2 C12, 3 C13}:
relax> spin.
[0]
[0]name(
[0]
[0]`@1', `C11', force=
[0]
[0]True)
relax> spin.
[0]
[0]name(
[0]
[0]`@2', `C12', force=
[0]
[0]True)
relax> spin.
[0]
[0]name(
[0]
[0]`@3', `C13', force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Number the spins.
spin_id: The spin identification string corresponding to a single spin.
number: The new spin number.
force: A flag which if True will cause the spin to be renumbered.
This simply allows spins to be numbered. The new number cannot correspond to an existing spin number.
The following sequence of commands will renumber the sequence {1 C1, 2 C2, 3 C3} to {-1 C1, -2 C2, -3 C3}:
relax> spin.
[0]
[0]number(
[0]
[0]`@1', -1, force=
[0]
[0]True)
relax> spin.
[0]
[0]number(
[0]
[0]`@2', -2, force=
[0]
[0]True)
relax> spin.
[0]
[0]number(
[0]
[0]`@3', -3, force=
[0]
[0]True)
The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.
If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.
Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.
Function for loading a saved program state.
state: The file name, which can be a string or a file descriptor object, of a saved program state.
dir: The name of the directory in which the file is found.
force: A boolean flag which if True will cause the current program state to be overwritten.
This function is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with `.bz2' appended followed by the file name with `.gz' appended.
Both the XML and pickled saved state formats are supported and automatically determined. For more advanced users, file descriptor objects are also supported. If the force flag is set to True, then the relax data store will be reset prior to the loading of the saved state.
The following commands will load the state saved in the file `save'.
relax> state.
[0]
[0]load(
[0]
[0]`save')
relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save')
Use one of the following commands to load the state saved in the bzip2 compressed file `save.bz2':
relax> state.
[0]
[0]load(
[0]
[0]`save')
relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save')
relax> state.
[0]
[0]load(
[0]
[0]`save.
[0]
[0]
[0]bz2')
relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save.
[0]
[0]
[0]bz2', force=
[0]
[0]True)
Function for saving the program state.
state: The file name, which can be a string or a file descriptor object, to save the current program state in.
dir: The name of the directory in which to place the file.
compress_type: The type of compression to use when creating the file.
force: A boolean flag which if set to True will cause the file to be overwritten.
pickle: A flag which if true will cause the state file to be a pickled object rather than the default XML format.
This user function will place the program state - the relax data store - into a file for later reloading or reference. The default format is an XML formatted file, but this can be changed to a Python pickled object through the pickle flag. Note, the pickle format is not human readable and often is not compatible with newer relax versions.
The default behaviour of this function is to compress the file using bzip2 compression. If the extension `.bz2' is not included in the file name, it will be added. The compression can, however, be changed to either no compression or gzip compression. This is controlled by the compress_type argument which can be set to
The following commands will save the current program state, uncompressed, into the file `save':
relax> state.
[0]
[0]save(
[0]
[0]`save', compress_type=
[0]
[0]0)
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save', compress_type=
[0]
[0]0)
The following commands will save the current program state into the bzip2 compressed file `save.bz2':
relax> state.
[0]
[0]save(
[0]
[0]`save')
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save')
relax> state.
[0]
[0]save(
[0]
[0]`save.
[0]
[0]
[0]bz2')
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save.
[0]
[0]
[0]bz2')
If the file `save' already exists, the following commands will save the current program state by overwriting the file.
relax> state.
[0]
[0]save(
[0]
[0]`save', force=
[0]
[0]True)
relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save', force=
[0]
[0]True)
Add an atom.
atom_name: The atom name.
res_name: The residue name.
res_num: The residue number.
pos: The atomic coordinates.
element: The element name.
atom_num: The optional atom number.
chain_id: The optional chain ID string.
segment_id: The optional segment ID string.
pdb_record: The optional PDB record name, e.g. `ATOM' or `HETATM'.
This allows atoms to be added to the internal structural object.
Connect two atoms.
index1: The global index of the first atom.
index2: The global index of the second atom.
This allows atoms to be connected in the internal structural object. The global index is normally equal to the PDB atom number minus 1.
Create a PDB file to represent the diffusion tensor.
scale: Value for scaling the diffusion rates.
file: The name of the PDB file.
dir: The directory where the file is located.
force: A flag which, if set to True, will overwrite the any pre-existing file.
This creates a PDB file containing an artificial geometric structure to represent the diffusion tensor. A structure must have previously been read into relax. The diffusion tensor is represented by an ellipsoidal, spheroidal, or spherical geometric object with its origin located at the centre of mass (of the selected residues). This diffusion tensor PDB file can subsequently read into any molecular viewer.
There are four different types of residue within the PDB. The centre of mass of the selected residues is represented as a single carbon atom of the residue `COM'. The ellipsoidal geometric shape consists of numerous H atoms of the residue `TNS'. The axes of the tensor, when defined, are presented as the residue `AXS' and consist of carbon atoms: one at the centre of mass and one at the end of each eigenvector. Finally, if Monte Carlo simulations were run and the diffusion tensor parameters were allowed to vary then there will be multiple `SIM' residues, one for each simulation. These are essentially the same as the `AXS' residue, representing the axes of the simulated tensors, and they will appear as a distribution.
As the Brownian rotational diffusion tensor is a measure of the rate of rotation about different axes - the larger the geometric object, the faster the diffusion of a molecule. For example the diffusion tensor of a water molecule is much larger than that of a macromolecule.
The effective global correlation time experienced by an XH bond vector, not to be confused with the Lipari and Szabo parameter
_e, will be approximately proportional to the component of the diffusion tensor parallel to it. The approximation is not exact due to the multiexponential form of the correlation function of Brownian rotational diffusion. If an XH bond vector is parallel to the longest axis of the tensor, it will be unaffected by rotations about that axis, which are the fastest rotations of the molecule, and therefore its effective global correlation time will be maximal.
To set the size of the diffusion tensor within the PDB frame the unit vectors used to generate the geometric object are first multiplied by the diffusion tensor (which has the units of inverse seconds) then by the scaling factor (which has the units of second Åand has the default value of 1.8e-6 s.Angstrom). Therefore the rotational diffusion rate per Åis equal the inverse of the scale value (which defaults to 5.56e5 s^-1.Angstrom^-1). Using the default scaling value for spherical diffusion, the correspondence between global correlation time,
diffusion rate, and the radius of the sphere for a number of discrete cases will be:
(see table 10.34)
The scaling value has been fixed to facilitate comparisons within or between publications, but can be changed to vary the size of the tensor geometric object if necessary. Reporting the rotational diffusion rate per Åwithin figure legends would be useful.
To create the tensor PDB representation, a number of algorithms are utilised. Firstly the centre of mass is calculated for the selected residues and is represented in the PDB by a C atom. Then the axes of the diffusion are calculated, as unit vectors scaled to the appropriate length (multiplied by the eigenvalue
,
,
,
,
, or
as well as the scale value), and a C atom placed at the position of this vector plus the centre of mass. Finally a uniform distribution of vectors on a sphere is generated using spherical coordinates. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These unit vectors, which are distributed within the PDB frame and are of 1 Åin length, are first rotated into the diffusion frame using a rotation matrix (the spherical diffusion tensor is not rotated). Then they are multiplied by the diffusion tensor matrix to extend the vector out to the correct length, and finally multiplied by the scale value so that the vectors reasonably superimpose onto the macromolecular structure. The last set of algorithms place all this information into a PDB file. The distribution of vectors are represented by H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines.
Create a PDB file representation of the distribution of XH bond vectors.
length: The length of the vectors in the PDB representation (meters).
file: The name of the PDB file.
dir: The directory to place the file into.
symmetry: A flag which if True will create a second chain with reversed XH bond orientations.
force: A flag which if True will overwrite the file if it already exists.
This creates a PDB file containing an artificial vectors, the length of which default to the length argument of 20 Å. A structure must have previously been read into relax. The origin of the vector distribution is located at the centre of mass (of the selected residues). This vector distribution PDB file can subsequently be read into any molecular viewer.
Because of the symmetry of the diffusion tensor reversing the orientation of the XH bond vector has no effect. Therefore by setting the symmetry flag two chains `A' and `B' will be added to the PDB file whereby chain `B' is chain `A' with the XH bonds reversed.
Delete all structural information.
This will delete all the structural information from the current data pipe. All spin and sequence information loaded from these structures will be preserved - this only affects the structural data.
Simply type:
relax> structure.
[0]
[0]
[0]delete(
[0]
[0])
Determine the rotational and translational displacement between a set of models.
model_from: The optional model number for the starting position of the displacement.
model_to: The optional model number for the ending position of the displacement.
atom_id: The atom identification string.
centroid: The alternative position of the centroid.
This user function allows the rotational and translational displacement between two models of the same structure to be calculated. The information will be printed out in various formats and held in the relax data store. This is directional, so there is a starting and ending position for each displacement. If the starting and ending models are not specified, then the displacements in all directions between all models will be calculated.
The atom ID, which uses the same notation as the spin ID strings, can be used to restrict the displacement calculation to certain molecules, residues, or atoms. This is useful if studying domain motions, secondary structure rearrangements, amino acid side chain rotations, etc.
By supplying the position of the centroid, an alternative position than the standard rigid body centre is used as the focal point of the motion. The allows, for example, a pivot of a rotational domain motion to be specified. This is not a formally correct algorithm, all translations will be zero, but does give an indication to the amplitude of the pivoting angle.
To determine the rotational and translational displacements between all sets of models, type:
relax> structure.
[0]
[0]
[0]displacement(
[0]
[0])
To determine the displacement from model 5 to all other models, type:
relax> structure.
[0]
[0]
[0]displacement(
[0]
[0]model_from=
[0]
[0]5)
To determine the displacement of all models to model 5, type:
relax> structure.
[0]
[0]
[0]displacement(
[0]
[0]model_to=
[0]
[0]5)
To determine the displacement of model 2 to model 3, type one of:
relax> structure.
[0]
[0]
[0]displacement(
[0]
[0]2, 3)
relax> structure.
[0]
[0]
[0]displacement(
[0]
[0]model_from=
[0]
[0]2, model_to=
[0]
[0]3)
Find the pivot point of the motion of a set of structures.
models: The list of models to use.
atom_id: The atom identification string.
init_pos: The initial position of the pivot.
This is used to find pivot point of motion between a set of structural models. If the list of models is not supplied, then all models will be used.
The atom ID, which uses the same notation as the spin ID strings, can be used to restrict the search to certain molecules, residues, or atoms. For example to only use backbone heavy atoms in a protein, use the atom ID of `@N,C,CA,O', assuming those are the names of the atoms from the structural file.
By supplying the position of the centroid, an alternative position than the standard rigid body centre is used as the focal point of the superimposition. The allows, for example, the superimposition about a pivot point.
Extract the atomic positions from the loaded structures for the given spins.
spin_id: The spin identification string.
ave_pos: A flag specifying if the position of the atom is to be averaged across models.
This allows the atomic positions of the spins to be extracted from the loaded structures. This is automatically performed by the structure.load_spins() user function, but if the sequence information is generated in other ways, this user function allows the structural information to be obtained.
If averaging the atomic positions, then average position of all models will be loaded into the spin container. Otherwise the positions from all models will be loaded separately.
For a model-free backbone amide nitrogen analysis whereby the N spins have already been created, to obtain the backbone N positions from the file `1F3Y.pdb' (which is a single protein), type the following two user functions:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`1F3Y.
[0]
[0]pdb')
relax> structure.
[0]
[0]
[0]get_pos(
[0]
[0]spin_id=
[0]
[0]`@N')
Load spins from the structure into the relax data store.
spin_id: The spin identification string.
ave_pos: A flag specifying if the position of the atom is to be averaged across models.
This allows a sequence to be generated within the relax data store using the atomic information from the structure already associated with this data pipe. The spin ID string is used to select which molecules, which residues, and which atoms will be recognised as spin systems within relax. If the spin ID is left unspecified, then all molecules, residues, and atoms will be placed within the data store (and all atoms will be treated as spins).
If averaging the atomic positions, then average position of all models will be loaded into the spin container. Otherwise the positions from all models will be loaded separately.
For a model-free backbone amide nitrogen analysis, to load just the backbone N sequence from the file `1F3Y.pdb' (which is a single protein), type the following two user functions:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`1F3Y.
[0]
[0]pdb')
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]`@N')
For an RNA analysis of adenine C8 and C2, guanine C8 and N1, cytidine C5 and C6, and uracil N3, C5, and C6, type the following series of commands (assuming that the PDB file with this atom naming has already been read):
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":A@C8")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":A@C2")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":G@C8")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":G@N1")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":C@C5")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":C@C6")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@N3")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@C5")
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@C6")
Alternatively using some Python programming:
relax> for id in [":A@C8", ":A@C2", ":G@C8", ":G@N1", ":C@C5", ":C@C6", ":U@N3", ":U@C5", ":U@C6"]:
relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]id)
Reading structures from PDB files.
file: The name of the PDB file.
dir: The directory where the file is located.
read_mol: If set, only the given molecule(s) will be read. The molecules are determined differently by the different parsers, but are numbered consecutively from 1. If unset, then all molecules will be loaded. By providing a list of numbers such as [1, 2], multiple molecules will be read.
set_mol_name: Set the names of the read molecules. If unset, then the molecules will be automatically labelled based on the file name or other information. This can either be a single name or a list of names.
read_model: If set, only the given model number(s) from the PDB file will be read. This can be a single number or list of numbers.
set_model_num: Set the model numbers of the loaded molecules. If unset, then the PDB model numbers will be preserved if they exist. This can be a single number or list of numbers.
parser: The PDB parser used to read the file.
The reading of PDB files into relax is quite a flexible procedure allowing for both models, defined as an ensemble of the same molecule but with different atomic positions, and different molecules within the same model. One of more molecules can exist in one or more models. The flexibility allows PDB models to be converted into different molecules and different PDB files loaded as the same molecule but as different models.
A few different PDB parsers can be used to read the structural data. The choice of which to use depends on whether your PDB file is supported by that reader. These are selected by setting the `parser' argument to one of:
In a PDB file, the models are specified by the MODEL PDB record. All the supported PDB readers in relax recognise this. The molecule level is quite different between the Scientific Python and internal readers. For how Scientific Python defines molecules, please see its documentation. The internal reader is far simpler as it defines molecules using the TER PDB record. In both cases, the molecules will be numbered consecutively from 1.
Setting the molecule name allows the molecule within the PDB (within one model) to have a custom name. If not set, then the molecules will be named after the file name, with the molecule number appended if more than one exists.
Note that relax will complain if it cannot work out what to do.
This is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with `.bz2' appended followed by the file name with `.gz' appended.
To load all structures from the PDB file `test.pdb' in the directory `~/pdb', including all models and all molecules, type one of:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', `~/pdb')
relax> structure.
[0]
[0]read_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', dir=
[0]
[0]`pdb')
To load the 10
model from the file `test.pdb' using the Scientific Python PDB parser and naming it `CaM', use one of:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM', parser=
[0]
[0]`scientific')
relax> structure.
[0]
[0]read_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM', parser=
[0]
[0]`scientific')
To load models 1 and 5 from the file `test.pdb' as two different structures of the same model, type one of:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', set_mol_name=
[0]
[0][`CaM_1', `CaM_2'], read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
To load the files `lactose_MCMM4_S1_1.pdb', `lactose_MCMM4_S1_2.pdb', `lactose_MCMM4_S1_3.pdb' and `lactose_MCMM4_S1_4.pdb' as models, type the following sequence of commands:
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_1.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]1)
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_2.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]2)
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_3.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]3)
relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_4.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]4)
The XYZ loading function.
file: The name of the XYZ file.
dir: The directory where the file is located.
read_mol: If set, only the given molecule(s) will be read.
set_mol_name: Set the names of the read molecules.
read_model: If set, only the given model number(s) from the XYZ file will be read.
set_model_num: Set the model numbers of the read molecules.
The XYZ files with different models, which defined as an ensemble of the same molecule but with different atomic positions, can be read into relax. If there are several molecules in one xyz file, please seperate them into different files and then load them individually. Loading different models and different molecules is controlled by the four keyword arguments `read_mol', `set_mol_name', `read_model', and `set_model_num'.
The `set_mol_name' argument is used to name the molecules within the XYZ (within one model). If not set, then the molecules will be named after the file name, with the molecule number appended if more than one exists.
Note that relax will complain if it cannot work out what to do.
To load all structures from the XYZ file `test.xyz' in the directory `~/xyz', including all models and all molecules, type one of:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', `~/xyz')
relax> structure.
[0]
[0]read_xyz(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]xyz', dir=
[0]
[0]`xyz')
To load the 10
model from the file `test.xyz' and naming it `CaM', use one of:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM')
relax> structure.
[0]
[0]read_xyz(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM')
To load models 1 and 5 from the file `test.xyz' as two different structures of the same model, type one of:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', set_mol_name=
[0]
[0][`CaM_1', `CaM_2'], read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])
To load the files `test_1.xyz', `test_2.xyz', `test_3.xyz' and `test_4.xyz' as models, type the following sequence of commands:
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_1.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_1', set_model_num=
[0]
[0]1)
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_2.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_2', set_model_num=
[0]
[0]2)
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_3.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_3', set_model_num=
[0]
[0]3)
relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_4.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_4', set_model_num=
[0]
[0]4)
Rotate the internal structural object about the given origin by the rotation matrix.
R: The rotation matrix in forwards rotation notation.
origin: The origin or pivot of the rotation.
model: The model to rotate (which if not set will cause all models to be rotated).
This is used to rotate the internal structural data by the given rotation matrix. If the origin is supplied, then this will act as the pivot of the rotation. Otherwise, all structural data will be rotated about the point [0, 0, 0]. The model argument can be used to rotate specific models.
Superimpose a set of models of the same structure.
models: The list of models to superimpose.
method: The superimposition method.
atom_id: The atom identification string.
centroid: The alternative position of the centroid.
This allows a set of models of the same structure to be superimposed to each other. Two superimposition methods are currently supported:
If the list of models is not supplied, then all models will be superimposed.
The atom ID, which uses the same notation as the spin ID strings, can be used to restrict the superimpose calculation to certain molecules, residues, or atoms. For example to only superimpose backbone heavy atoms in a protein, use the atom ID of `@N,C,CA,O', assuming those are the names of the atoms from the structural file.
By supplying the position of the centroid, an alternative position than the standard rigid body centre is used as the focal point of the superimposition. The allows, for example, the superimposition about a pivot point.
To superimpose all sets of models, type one of:
relax> structure.
[0]
[0]superimpose(
[0]
[0])
relax> structure.
[0]
[0]superimpose(
[0]
[0]method=
[0]
[0]`fit to mean')
To superimpose the models 1, 2, 3, 5 onto model 4, type:
relax> structure.
[0]
[0]superimpose(
[0]
[0]models=
[0]
[0][4, 1, 2, 3, 5], method=
[0]
[0]`fit to first')
To superimpose an ensemble of protein structures using only the backbone heavy atoms, type one of:
relax> structure.
[0]
[0]superimpose(
[0]
[0]atom_id=
[0]
[0]`@N,C,CA,O')
relax> structure.
[0]
[0]superimpose(
[0]
[0]method=
[0]
[0]`fit to mean', atom_id=
[0]
[0]`@N,C,CA,O')
To superimpose model 2 onto model 3 using backbone heavy atoms, type one of:
relax> structure.
[0]
[0]superimpose(
[0]
[0][3, 2], `fit to first', `@N,C,CA,O')
relax> structure.
[0]
[0]superimpose(
[0]
[0]models=
[0]
[0][3, 2], method=
[0]
[0]`fit to first', atom_id=
[0]
[0]`@N,C,CA,O')
Laterally displace the internal structural object by the translation vector.
T: The translation vector.
model: The model to translate (which if not set will cause all models to be translate).
atom_id: The atom identification string.
This is used to translate the internal structural data by the given translation vector. The model argument can be used to translate specific models.
Extract and store the bond vectors from the loaded structures in the spin container.
attached: The name of the second atom which attached to the spin of interest. Regular expression is allowed, for example `H*'.
spin_id: The spin identification string.
model: The model to extract bond vectors from (which if not set will cause the vectors of all models to be extracted).
verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.
ave: A flag which if True will cause the bond vectors from all models to be averaged. If vectors from only one model is extracted, this argument will have no effect.
unit: A flag which if True will cause the unit vector to calculated rather than the full length bond vector.
For a number of types of analysis, bond vectors or unit bond vectors are required for the calculations. This user function allows these vectors to be extracted from the loaded structures. The bond vector will be that from the atom associated with the spin system loaded in relax to the bonded atom specified by the `attached' argument. For example if the attached atom is set to `H' and the protein backbone amide spins `N' are loaded, the all `N-H' vectors will be extracted. But if set to `CA', all atoms named `CA' in the structures will be searched for and all `N-Ca' bond vectors will be extracted.
The extraction of vectors can occur in a number of ways. For example if an NMR structure with N models is loaded or if multiple molecules, from any source, of the same compound are loaded as different models, there are three options for extracting the bond vector. Firstly the bond vector of a single model can be extracted by setting the model number. Secondly the bond vectors from all models can be extracted if the model number is not set and the average vector flag is not set. Thirdly, if the model number is not set and the average vector flag is set, then a single vector which is the average for all models will be calculated.
To extract the XH vectors of the backbone amide nitrogens where in the PDB file the backbone nitrogen is called `N' and the attached atom is called `H', assuming multiple types of spin have already been loaded, type one of:
relax> structure.
[0]
[0]vectors(
[0]
[0]spin_id=
[0]
[0]`@N')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H', spin_id=
[0]
[0]`@N')
relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`H', spin_id=
[0]
[0]`@N')
If the attached atom is called `HN', type:
relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`HN', spin_id=
[0]
[0]`@N')
For the `CA' spin bonded to the `HA' proton, type:
relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`HA', spin_id=
[0]
[0]`@CA')
If you are working with RNA, you can use the residue name identifier to calculate the vectors for each residue separately. For example to calculate the vectors for all possible spins in the bases, type:
relax> structure.
[0]
[0]vectors(
[0]
[0]`H2', spin_id=
[0]
[0]`:A')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H8', spin_id=
[0]
[0]`:A')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H1', spin_id=
[0]
[0]`:G')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H8', spin_id=
[0]
[0]`:G')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H5', spin_id=
[0]
[0]`:C')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H6', spin_id=
[0]
[0]`:C')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H3', spin_id=
[0]
[0]`:U')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H5', spin_id=
[0]
[0]`:U')
relax> structure.
[0]
[0]vectors(
[0]
[0]`H6', spin_id=
[0]
[0]`:U')
Alternatively, assuming the desired spins have been loaded, regular expression can be used:
relax> structure.
[0]
[0]vectors(
[0]
[0]`H*')
Writing structures to a PDB file.
file: The name of the PDB file.
dir: The directory where the file is located.
model_num: Restrict the writing of structural data to a single model in the PDB file.
compress_type: The type of compression to use when creating the file.
force: A flag which if set to True will cause any pre-existing files to be overwritten.
This will write all of the structural data loaded in the current data pipe to be converted to the PDB format and written to file. Specifying the model number allows single models to be output.
The default behaviour of this function is to not compress the file. The compression can, however, be changed to either bzip2 or gzip compression. If the `.bz2' or `.gz' extension is not included in the file name, it will be added. This behaviour is controlled by the compress_type argument which can be set to
To write all models and molecules to the PDB file `ensemble.pdb' within the directory `~/pdb', type one of:
relax> structure.
[0]
[0]write_pdb(
[0]
[0]`ensemble.
[0]
[0]pdb', `~/pdb')
relax> structure.
[0]
[0]write_pdb(
[0]
[0]file=
[0]
[0]`ensemble.
[0]
[0]pdb', dir=
[0]
[0]`pdb')
To write model number 3 into the new file `test.pdb', use one of:
relax> structure.
[0]
[0]write_pdb(
[0]
[0]`test.
[0]
[0]pdb', model_num=
[0]
[0]3)
relax> structure.
[0]
[0]write_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', model_num=
[0]
[0]3)
Display all system information relating to this version of relax.
This will display all of the relax, Python, python package and hardware information currently being used by relax. This is useful for seeing if all packages are up to date and if the correct software versions are being used. It is also very useful information for reporting relax bugs.
Function which executes the user supplied shell command.
Specify the temperature of an experiment.
id: The experiment identification string.
temp: The temperature of the experiment.
This function allows the temperature of an experiment to be set. In certain analyses, for example those which use pseudocontact shift data, knowledge of the temperature is essential.
Copy spin specific data values from one data pipe to another.
pipe_from: The name of the pipe to copy from.
pipe_to: The name of the pipe to copy to.
param: The parameter to copy. Only one parameter may be selected.
If this is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.
To copy the CSA values from the data pipe `m1' to `m2', type:
relax> value.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2', `csa')
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
WILL match both `S2' and `s2'.
`s2s'.
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
Setting a parameter value may have no effect depending on which model-free model is chosen, for example if
values and
values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.
Note that the
values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:
* frequency) ** 2
where:
is in the namespace of relax, ie just type `pi'.
(see table 10.35)
In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.
(see table 10.36)
Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.
(see table 10.37)
Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle
of the third state is specified using the string `gamma2'.
(see table 10.38)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Display spin specific data values.
param: The parameter to display. Only one parameter may be selected.
To show all CSA values, type:
relax> value.
[0]
[0]
[0]display(
[0]
[0]`csa')
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
WILL match both `S2' and `s2'.
`s2s'.
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.39)
(see table 10.40)
(see table 10.41)
(see table 10.42)
(see table 10.43)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Read spin specific data values from a file.
param: The parameter. Only one parameter may be selected.
scaling: The factor to scale parameters by.
file: The name of the file containing the values.
dir: The directory where the file is located.
spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).
mol_name_col: The molecule name column (alternative to the spin_id_col).
res_num_col: The residue number column (alternative to the spin_id_col).
res_name_col: The residue name column (alternative to the spin_id_col).
spin_num_col: The spin number column (alternative to the spin_id_col).
spin_name_col: The spin name column (alternative to the spin_id_col).
data_col: The RDC data column.
error_col: The experimental error column.
sep: The column separator (the default is white space).
spin_id: The spin ID string to restrict the loading of data to certain spin subsets.
The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the molecule name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin ID string can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.
If this is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.
To load 15N CSA values from the file `csa_values' in the directory `data', where spins are only identified by residue name and number, type one of the following:
relax> value.
[0]
[0]read(
[0]
[0]`csa', `data/csa_value', spin_id=
[0]
[0]`@N')
relax> value.
[0]
[0]read(
[0]
[0]`csa', `csa_value', dir=
[0]
[0]`data', spin_id=
[0]
[0]`@N')
relax> value.
[0]
[0]read(
[0]
[0]param=
[0]
[0]`csa', file=
[0]
[0]`csa_value', dir=
[0]
[0]`data', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4, spin_id=
[0]
[0]`@N')
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
WILL match both `S2' and `s2'.
`s2s'.
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
Setting a parameter value may have no effect depending on which model-free model is chosen, for example if
values and
values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.
Note that the
values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:
* frequency) ** 2
where:
is in the namespace of relax, ie just type `pi'.
(see table 10.44)
In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.
(see table 10.45)
Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.
(see table 10.46)
Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle
of the third state is specified using the string `gamma2'.
(see table 10.47)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Set spin specific data values.
val: The value(s).
param: The parameter(s).
spin_id: The spin identifier.
If this function is used to change values of previously minimised results, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset to None.
The val argument can be None, a single value, or an array of values while the parameter argument can be None, a string, or array of strings. The choice of which combination determines the behaviour of this function. The following table describes what occurs in each instance. The Value column refers to the `val' argument while the Param column refers to the `param' argument. In these columns, `None' corresponds to None, `1' corresponds to either a single value or single string, and `n' corresponds to either an array of values or an array of strings.
(see table 10.48)
To set the parameter values for the current data pipe to the default values, for all spins, type:
relax> value.
[0]
[0]set(
[0]
[0])
To set the parameter values of residue 10, which is in the current model-free data pipe `m4' and has the parameters {
,
,
}, the following can be used.
term is the value for the first given field strength.
relax> value.
[0]
[0]set(
[0]
[0][0.97, 2.048*1e-9, 0.149], spin_id=
[0]
[0]`:10')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.97, 2.048*1e-9, 0.149], spin_id=
[0]
[0]`:10')
To set the CSA value of all spins to the default value, type:
relax> value.
[0]
[0]set(
[0]
[0]param=
[0]
[0]`csa')
To set the CSA value of all spins to -172 ppm, type:
relax> value.
[0]
[0]set(
[0]
[0]-172 * 1e-6, `csa')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]-172 * 1e-6, param=
[0]
[0]`csa')
To set the NH bond length of all spins to 1.02 Å, type:
relax> value.
[0]
[0]set(
[0]
[0]1.02 * 1e-10, `r')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]1.02 * 1e-10, param=
[0]
[0]`r')
To set both the bond length and the CSA value to the default values, type:
relax> value.
[0]
[0]set(
[0]
[0]param=
[0]
[0][`r', `csa'])
To set both
and
to 100 ps, type:
relax> value.
[0]
[0]set(
[0]
[0]100e-12, [`tf', `ts'])
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]100e-12, param=
[0]
[0][`tf', `ts'])
To set the
and
parameter values of residue 126, Ca spins to 0.56 and 13 ps, type:
relax> value.
[0]
[0]set(
[0]
[0][0.56, 13e-12], [`s2', `te'], `:126@Ca')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.56, 13e-12], param=
[0]
[0][`s2', `te'], spin_id=
[0]
[0]`:126@Ca')
relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.56, 13e-12], param=
[0]
[0][`s2', `te'], spin_id=
[0]
[0]`:126@Ca')
If the spin ID is left unset, then this will be applied to all spins. If the data is global non- spin specific data, such as diffusion tensor parameters, supplying the spin identifier will terminate the program with an error.
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
WILL match both `S2' and `s2'.
`s2s'.
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
Setting a parameter value may have no effect depending on which model-free model is chosen, for example if
values and
values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.
Note that the
values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:
* frequency) ** 2
where:
is in the namespace of relax, ie just type `pi'.
(see table 10.49)
(see table 10.50)
In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.
(see table 10.51)
These default values are found in the file `physical_constants.py'.
(see table 10.52)
If the diffusion tensor has not been setup, use the more powerful function `diffusion_tensor.init' to initialise the tensor parameters. This function cannot be used to initialise a diffusion tensor.
The units of the parameters are:
.
,
,
,
,
,
,
.
and
.
,
,
,
,
).
When setting a diffusion tensor parameter, the residue number has no effect. As the internal parameters of spherical diffusion are {tm}, spheroidal diffusion are {
,
,
,
}, and ellipsoidal diffusion are {
,
,
,
,
,
}, supplying geometric parameters must be done in the following way. If a single geometric parameter is supplied, it must be one of
,
,
,
, or
. For the parameters
,
,
,
, and
, it is not possible to determine how to use the currently set values together with the supplied value to calculate the new internal parameters. For spheroidal diffusion, when supplying multiple geometric parameters, the set must belong to one of
,
},
,
},
,
},
,
},
,
},
where either
,
, or both orientational parameters can be additionally supplied. For ellipsoidal diffusion, again when supplying multiple geometric parameters, the set must belong to one of
,
,
},
,
,
},
,
,
},
where any number of the orientational parameters,
,
, or
can be additionally supplied.
(see table 10.53)
(see table 10.54)
Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.
(see table 10.55)
These values are completely arbitrary as peak heights (or volumes) are extremely variable and the Rx value is a compensation for both the R
and R
values.
(see table 10.56)
Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle
of the third state is specified using the string `gamma2'.
(see table 10.57)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
(see table 10.58)
In this table, N is the total number of states and c is the index of a given state ranging from 0 to N-1. The default probabilities are all set to be equal whereas the angles are given a range of values so that no 2 states are equal at the start of optimisation.
Note that setting the probability for state N will do nothing as it is equal to one minus all the other probabilities.
Write spin specific data values to a file.
param: The parameter.
file: The name of the file.
dir: The directory name.
bc: A flag which if True will cause the back calculated values to be written to file rather than the actual data.
force: A flag which, if set to True, will cause the file to be overwritten.
The values corresponding to the given parameter will be written to file.
To write the CSA values to the file `csa.txt', type one of:
relax> value.
[0]
[0]write(
[0]
[0]`csa', `csa.
[0]
[0]txt')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`csa', file=
[0]
[0]`csa.
[0]
[0]txt')
To write the NOE values to the file `noe', type one of:
relax> value.
[0]
[0]write(
[0]
[0]`noe', `noe.
[0]
[0]out')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out')
relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out', force=
[0]
[0]True)
The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.
This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:
WILL match both `S2' and `s2'.
`s2s'.
Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.
(see table 10.59)
(see table 10.60)
(see table 10.61)
(see table 10.62)
(see table 10.63)
The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.
Function for viewing the collection of molecules extracted from the PDB file.
relax> vmd.
[0]
[0]view(
[0]
[0])
Edward d'Auvergne 2012-03-20